---
title: "Survey design: power, precision and sample size"
date: "29 April 2017"
output: rmarkdown::html_vignette
#output: rmarkdown::pdf_document
vignette: >
  %\VignetteIndexEntry{Survey design}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

This vignette covers the use of functions `incpower` and `incprecision`.

## Function `incpower`

For this related set of calculations, we use the term "power" to mean the probability of obtaining a "statistically significant" result, *of the correct sign* in the estimation of an incidence difference, given some assumptions on effect size, recency test properties, and sample specification. See the vignette "introduction", especially the glossary, for some crucial details.

Function `incpower` primarily calculates samples sizes required to achieve desired power, or the power available at specified sample size(s).
This requires study context defining parameter values--such as hypothetical incidence rates, prevalences, coverage rates, design effects, and the assay characteristics known as *mean duration of recent infection* (MDRI) and *false recent rate* (FRR)--and returns .

A number of supplementary outputs are also supplied, such as

* demonstrative relative standard errors and confidence limits, in the case that point estimates attain the true/expected values.  
* expected survey counts, assuming a non structured sampling frame.

### Examples

Consider calculating the power to infer the correct ordering of an incidence of 5\% and one of 3\%, at a shared prevalences of 20\%, given a single set of recency test property estimates i.e. one value for each of MDRI, the RSE of MDRI, FRR, the RSE of FRR, and time cutoff T namely, in order: 200 days, 5\%, 1\%, 20\%, and 730 days. Assume complete coverage of recency status ascertainment, and no survey design effects. Finally, envision a common study sample size of 5000 persons and set $\alpha$ to 5\%. That power, as opposed to sample size (the default) is the desired output, is captured in the specification of the argument `Power = "out"` and `SS = NULL`.


```{r, echo=FALSE}
library("inctools")
```


```{r, echo=TRUE}
incpower(I1 = 0.05, I2 = 0.03, PrevH1 = 0.20, PrevH2 = 0.20, n1 = 5000,
        n2 = 5000, alpha = 0.05,Power = "out", SS = NULL, CR = 1, DE_H = 1,
        DE_R = 1, BMest = "same.test", MDRI = 200, RSE_MDRI = 0.05, FRR = 0.01,
        RSE_FRR = 0.20, BigT = 730)
```

Here the output returns that the power of this particular test is 0.858. In the limit of infinite sample size power approaches one.

For the benefit of survey planning (such as costing) the returned `Implied.Subject.Counts` object captures demonstrative survey counts in the case that expectation values are precisely attained.

To calculate the required (common) sample size for two surveys, to obtain a desired power:

* omit `n1` and `n2` or set both to `"both"`
* set `SS = "out"`
* set `Power` to the desired value.


```{r, echo=TRUE}
incpower(I1 = 0.05, I2 = 0.03, PrevH1 = 0.20, PrevH2 = 0.15, alpha = 0.05,
        Power = 0.8, SS = "out", CR = 1, DE_H = 1, DE_R = 1,
        BMest = "FRR.indep", MDRI = 200, RSE_MDRI = 0.05, FRR = c(0.01,0.009),
        RSE_FRR = c(0.20,0.22), BigT = 730)
```

The function call outputs that the necessary common study sample size is 4122 persons per study to achieve the desired 80\% power given the specified population parameters and assay characteristics.



## Function `incprecision`

This function summarizes performance of a recent infection test into a standard error of the incidence estimate, given the estimated test properties and hypothetical survey context or the sample size necessary for a given level of precision.


### Examples

The function invocation below returns the necessary sample size to have RSE of the incidence estimator equal to 25\%, given a hypothetical prevalence, coverage rate, and recency test parameter estimates. Note that `n = "out"`.

```{r, echo=TRUE}
incprecision(I = 0.015, RSE_I = 0.25, PrevH = 0.2, CR = 1, MDRI = 200,
            RSE_MDRI = 0.05, FRR = 0.01, RSE_FRR = 0.2, BigT = 730,
            DE_H = 1.1, DE_R = 1.1, n = 'out')
```



Up to two arguments can be specified as ranges, with the input parameter `step` specifying the number of increments between the endpoints of the two ranges that are supplied under the argument name.
Consider the calculation of sample size requirements for prevalence and incidence varied from 10 to 20\% and 1.5 to 2\% respectively:

```{r, echo=TRUE}
incprecision(I = c(0.015,0.02), RSE_I = 0.25, PrevH = c(0.10,0.20), CR = 1,
             MDRI = 200, RSE_MDRI = 0.05, FRR = 0.01, RSE_FRR = 0.2, BigT = 700,
             DE_H = 1, DE_R = 1, n = 'out', step = 3)
```


To calculate the RSE of incidence over a range of 5 values of prevalence of positivity, at a sample size of 5000:

```{r, echo=TRUE}
incprecision(I = 0.017, RSE_I = 'out', PrevH = c(0.10,0.20), CR = 1, MDRI = 211,
             RSE_MDRI = 0.05, FRR = 0.009, RSE_FRR = 0.2, BigT = 720, n = 5000,
             step = 5)
```

