---
title: "Using the NNTbiomarker package"
author: "Roger Day"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using the NNTbiomarker package}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

## Planning clinically relevant biomarker validation studies using the “number needed to treat” concept.


This package supports stepping through the design of a biomarker validation study. There are two "shiny"-based web apps for interaction and visualization:

* [shinyCombinePlots](#shinyCombinePlots) 

* [shinyElicit](#shinyElicit)

> See the vignette 'The_Biomarker_Crisis' for the motivation.

***
<a name=shinyCombinePlots id="shinyCombinePlots" > </a>

## shinyCombinePlots 

------>   *Available at [http://trials.shinyapps.io/shinyCombinePlots](http://trials.shinyapps.io/shinyCombinePlots) or via runCombinePlots()*

Displays plots of an NNT scale together with a "contra-Bayes" plot which maps from NNTs or PVs (predictive values) to sensitivity and specificity.  

The NNT scale allows a clinical trial designer or team to specify a discomfort zone and values for NNT outside that zone, where clinical decisions would be clearer:

\[NN{T_{Pos}} < \underbrace {NN{T_{Lower}} < NN{T_{Upper}}}_{{\rm{discomfort}}\;{\rm{ range}}} < NN{T_{Neg}}\]


#### Prospective study design

For a prospective study design, the design targets are easy:

\[PPV > 1/NN{T_{Lower}},\quad NPV > 1 - 1/NN{T_{Upper}}\]

#### Retrospective study design

For a retrospective study design, given a prevalence value,
produce a plot displaying the achievable contours of
either predictive values or NNT values.
This plot uses the "contra-Bayes" theorem, sesp.from.pv(), as follows:

\[
\begin{array}{l}
SP = specificity = \frac{{PPO - Odds}}{{PPO - NP{O^{ - 1}}}}\\
SN = sensitivity = \frac{{NPO - Odd{s^{ - 1}}}}{{NPO - PP{O^{ - 1}}}}
\end{array}
\]

where 

* $Odds = Pr(BestToAct) / Pr(BestToWait)$ 

* $PPO = PPV / (1 – PPV)$ = the “positive predictive odds”

* $NPO = NPV / (1 – NPV)$ = the “negative predictive odds”.


*__TODO:__*

Calculating anticipated results for prospective and retrospective studies 
from sample sizes.

***
<a name=shinyElicit id="shinyElicit" > </a>

## shinyElicit

------>    *Available at [http://trials.shinyapps.io/shinyElicit](http://trials.shinyapps.io/shinyElicit) or via runElicit()*

Embeds the shinyCombinePlots into a sequence of steps required to elicit the desired clinical applicability. Walking through the steps will lead to a study deign responsive to patients' needs.

The table near the top that drives the process can be shown or hidden with the toggle at the left of the window. The table is shown or hidden via the checkbox at the upper left.


<img src=Screenshot-stepsTableInitial.png height="200">

After the user sets each **"Is this step done?"** toggle  to **"Done"**, 
the button at the top is enabled.
This button is labeled:  

*When all steps are Done, you can click here for a report*

*__TODO:__*

The report is not yet implemented. 

