Rebuilt vignettes and ran CRAN check.

inctools/vignettes/Introduction.html

@@ -223,51 +223,7 @@ <h3>Crucial note on choice of null hypothesis, calculation of p-values and meani
 <li>hypothesize that the estimated value of the variance of the incidence difference estimate (calculated carefully in accordance with the choice of how test properties are shared between the surveys) is a good estimate of the actual variance of the incidence difference. (This is equivalent to a routinely made assumption in less complex situations)</li>
 <li>allow the prevalence for each context to be independently estimated from the data from that context. (Note that even if the data does not support the rejection of the hypothesis that the prevalences are identical, benchmarking indicates that there is little or no advantage in constructing the null hypothesis to include equal prevalence.)</li>
 </ul>
-<p>The preceding assumptions allow the calculation of a p-value, which is done according to a two-tailed test, capturing the point that the experimenter has no basis to pre-determine the acceptable direction of any incidence difference.   Note that while it is common to report “power” as simply the probability of correctly rejecting a null hypothesis, without regard to whether the inferred direction of difference is in correspondence with the underlying reality, the present construction specifically presumes a two-tailed test, where the direction of any particular inferred difference will be either correct or incorrect. Hence, <em>inctools</em> calculates the probability of <em>correctly</em> detecting the sign of the incidence difference through the rejection of the null hypothesis throug the attainment of a below-threshold <em>p value</em>. Numerically, the probability of rejecting the null hypothesis, but with the incorrect direction for the inferred effect, will usually be <em>very</em> small, unless the study design has no useful statistical power in any case. The primary difference between this implementation and an alternative likely to be proposed, is in the insistence on a two tailed test, which should not be controversial in this situation as it would be difficult to defend the claim that survey implementers can claim to know the change in</p>
-<!--   #not-for-release -->
-<!--
-## The Empirical Bootstrapping Option
-
-Functions `incprops` and `inccounts` both admit the option of bootstrapping. The default multivariate delta method approximation to the variance of the incidence estimator is likely to be more than adequate for most cases where reasonably informative incidence estimate are possible.
-
-inputs that are normal, however the method is still only a linear approximation. Since there are situations where the higher order terms in the Taylor expansion of variance may contribute non-negligibly to the variance estimator, and since it may be the case that both FRR and structured survey data may not be exactly normally distributed, we have programmed an empirical bootstrapping option for users wishing to make non-parametric inference on differences in proportions.
-
-This method is called in `incprops` and `inccounts` by adding the option `Boot = TRUE`. The method is described below.
-
-We start with estimates on parameters that are derived from data. So we have estimates:
-
-* $\widehat{\text{PrevH}}$,
-* $\widehat{\text{PrevR}}$,
-* $\widehat{\Omega}$,
-* $\widehat{\beta}$,
-
-along with their respective estimates of variance.
-
-We resample a multivariate normal distribution with argument `EMPIRICAL = TRUE` to the function `mvrnorm` from the *MASS* package, which coerces the samples such that if we take the mean and variance of any number of samples of $\Omega_T$, say, we will get the exact mean and variance we entered into the multivariate normal sampler as parameters from the distribution. Each unique re-sample for each estimator $\varphi$ is a B-tuple of values such that the B-tuple mean equals $\widehat{\varphi}$ and its variance exactly equals the variance of the original estimator. Corresponding to each column of this matrix is a single "bootstrap" estimate $\mathbb{I}$, the estimate of incidence.
-
-\noindent
-So we have sample matrix
-\[ \mathbf{B} = \left( \begin{array}{ccccc}
-\text{PrevH}_\text{1} & \text{PrevH}_\text{2} & \text{PrevH}_\text{3} & \cdots & \text{PrevH}_\text{B}\\
-\text{PrevR}_\text{1} & \text{PrevR}_\text{2} & \text{PrevR}_\text{3} & \cdots & \text{PrevR}_\text{B}\\
-\Omega_1 & \Omega_2 & \Omega_3 & \cdots&\Omega_B \\
-\beta_1 & \beta_2 & \beta_3 &\cdots & \beta_B
-\end{array} \right)\]
-$$  \  \ \  \ \  \ \   \ \  \ \  \ \  \ \  \downarrow\ \ \ \ \ \ \  \ \ \  \ \  \downarrow\ \ \ \ \ \ \ \ \  \ \  \   \downarrow\ \ \ \ \  \ \ \  \cdots\ \ \ \ \  \ \downarrow \ \ \ \ \ \ \  \ \
-$$
-$$\ \ \ \  \  \ \  \ \  \ \   \ \  \ \  \ \ \ \ \ \ \  \mathbb{I}_1 \ \ \ \ \ \ \ \ \   \ \  \  \ \mathbb{I}_2\ \ \  \ \ \ \ \ \  \ \ \  \  \mathbb{I}_3\ \ \  \  \  \ \ \ \cdots\ \ \ \ \ \  \ \ \mathbb{I}_B \ \ \ \ \ \ \  \ \ \ \ \ \
-$$
-which is sampled in such a way that, for example, for empirical bootstrap sample $\Omega_B$
-$$
-\sum_{b=1}^B\Omega_b = \widehat{\Omega}\ \ \text{(the $observed$ value of the estimator)}
-$$
-and
-$$
-\frac{1}{B-1}\sum_{b=1}^B\Omega_b = s^2_{\Omega}\ \ \text{(the $observed$ SD of the estimator)}
-$$
-
-The bootstrap option produces most of the statistics given by running the functions using a delta method approximation, however the estimate of RSE of the incidence estimator at infinite sample size, which is calculated by letting sample size $n$ tend toward infinity in the limit in the components of the variance of incidence estimator, is not produced.
--->
+<p>The preceding assumptions allow the calculation of a p-value, which is done according to a two-tailed test, capturing the point that the experimenter has no basis to pre-determine the acceptable direction of any incidence difference.   Note that while it is common to report “power” as simply the probability of correctly rejecting a null hypothesis, without regard to whether the inferred direction of difference is in correspondence with the underlying reality, the present construction specifically presumes a two-tailed test, where the direction of any particular inferred difference will be either correct or incorrect. Hence, <em>inctools</em> calculates the probability of <em>correctly</em> detecting the sign of the incidence difference through the rejection of the null hypothesis throug the attainment of a below-threshold <em>p value</em>. Numerically, the probability of rejecting the null hypothesis, but with the incorrect direction for the inferred effect, will usually be <em>very</em> small, unless the study design has no useful statistical power in any case. The primary difference between this implementation and an alternative likely to be proposed, is in the insistence on a two tailed test, which should not be controversial in this situation as it would be difficult to defend the claim that survey implementers can claim to know, in advance, the direction of a change in incidence.</p>
 </div>
 </div>
 

inctools/vignettes/SurveyDesign.R

@@ -16,7 +16,7 @@ incpower(I1 = 0.05, I2 = 0.03, PrevH1 = 0.20, PrevH2 = 0.15, alpha = 0.05,
 ## ---- 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, n = 'out')
+            DE_H = 1.1, DE_R = 1.1, n = 'out')
 
 ## ---- echo=TRUE----------------------------------------------------------
 incprecision(I = c(0.015,0.02), RSE_I = 0.25, PrevH = c(0.10,0.20), CR = 1,
@@ -28,9 +28,3 @@ 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)
 
-## ---- echo=TRUE----------------------------------------------------------
-incpower(I1 = 0.05, I2 = 0.03, PrevH1 = 0.20, PrevH2 = 0.15, n1 = 5000,
-        n2 = "out", alpha = 0.05, Power = 0.8, SS = "out", CR = 1, DE_H = 1,
-        DE_R = 1, BMest = "same.test", MDRI = 200, RSE_MDRI = 0.05, FRR = 0.01,
-        RSE_FRR = 0.21, BigT = 730)
-

inctools/vignettes/SurveyDesign.html

@@ -158,15 +158,14 @@ <h3>Examples</h3>
 <div id="function-incprecision" class="section level2">
 <h2>Function <code>incprecision</code></h2>
 <p>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.</p>
-<p>Up to two arguments can be specified as tuples, with the input parameter <code>step</code> specifying the number of points analyzed between the endpoints of the given tuple. This specification will yield output for each value in the step for the output parameters that take as argument one of the varying inputs. See the second and third example below for an illustration of this output.</p>
 <div id="examples-1" class="section level3">
 <h3>Examples</h3>
-<p>The function call below returns the necessary sample size to have RSE of the incidence estimator equal to 25%, given a hypothetical prevalence, coverage rate, and assay tests parameter estimates. Note here the design effects for the test of HIV positivity are set to 1.1 and that sample size is set to <code>n = &quot;out&quot;</code>.</p>
+<p>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 <code>n = &quot;out&quot;</code>.</p>
 <div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">incprecision</span>(<span class="dt">I =</span> <span class="fl">0.015</span>, <span class="dt">RSE_I =</span> <span class="fl">0.25</span>, <span class="dt">PrevH =</span> <span class="fl">0.2</span>, <span class="dt">CR =</span> <span class="dv">1</span>, <span class="dt">MDRI =</span> <span class="dv">200</span>,
             <span class="dt">RSE_MDRI =</span> <span class="fl">0.05</span>, <span class="dt">FRR =</span> <span class="fl">0.01</span>, <span class="dt">RSE_FRR =</span> <span class="fl">0.2</span>, <span class="dt">BigT =</span> <span class="dv">730</span>,
-            <span class="dt">DE_H =</span> <span class="fl">1.1</span>, <span class="dt">DE_R =</span> <span class="dv">1</span>, <span class="dt">n =</span> <span class="st">'out'</span>)</code></pre></div>
+            <span class="dt">DE_H =</span> <span class="fl">1.1</span>, <span class="dt">DE_R =</span> <span class="fl">1.1</span>, <span class="dt">n =</span> <span class="st">'out'</span>)</code></pre></div>
 <pre><code>## $sample.size
-## [1] 3634
+## [1] 3985
 ## 
 ## $Prev.HIV.and.recent
 ## [1] 0.00833
@@ -178,12 +177,11 @@ <h3>Examples</h3>
 ## [1] 0.07606
 ## 
 ## $RSE.PrevH
-## [1] 0.0348
+## [1] 0.03323
 ## 
 ## $RSE.PrevR
-## [1] 0.03558</code></pre>
-<p>The function call returns that the necessary sample size for the desired precision in the incidence estimator is 3634 persons. Prevalence of being HIV positive and recently infected is 0.8%, prevalence of being HIV positive and nonrecently infected is 19%. The RSE of the incidence estimator at infinite sample size is 7.6%, and the RSE of prevalence of positivity for HIV is 3.4% and the RSE of prevalence of recency is 3.55%.</p>
-<p>Next consider the function call for a tuple of prevalence of HIV positivity values and incidence estimates that range in value between 10 and 20% and 1.5 and 2% respectively. The function now outputs a range of values 3 values for each output parameter that is dependent upon these two varying quantities, as well as the normal output from a single parameter function call when the output does not depend on the varying parameters. Note again that sample size is set to <code>n = &quot;out&quot;</code>.</p>
+## [1] 0.03564</code></pre>
+<p>Up to two arguments can be specified as ranges, with the input parameter <code>step</code> 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:</p>
 <div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">incprecision</span>(<span class="dt">I =</span> <span class="kw">c</span>(<span class="fl">0.015</span>,<span class="fl">0.02</span>), <span class="dt">RSE_I =</span> <span class="fl">0.25</span>, <span class="dt">PrevH =</span> <span class="kw">c</span>(<span class="fl">0.10</span>,<span class="fl">0.20</span>), <span class="dt">CR =</span> <span class="dv">1</span>,
              <span class="dt">MDRI =</span> <span class="dv">200</span>, <span class="dt">RSE_MDRI =</span> <span class="fl">0.05</span>, <span class="dt">FRR =</span> <span class="fl">0.01</span>, <span class="dt">RSE_FRR =</span> <span class="fl">0.2</span>, <span class="dt">BigT =</span> <span class="dv">700</span>,
              <span class="dt">DE_H =</span> <span class="dv">1</span>, <span class="dt">DE_R =</span> <span class="dv">1</span>, <span class="dt">n =</span> <span class="st">'out'</span>, <span class="dt">step =</span> <span class="dv">3</span>)</code></pre></div>
@@ -222,8 +220,7 @@ <h3>Examples</h3>
 ## I = 0.015      0.02061      0.02061     0.02061
 ## I = 0.0175     0.02975      0.02975     0.02975
 ## I = 0.02       0.03817      0.03817     0.03817</code></pre>
-<p>So for example in the first listed output, the sample size necessary for a given precision in the incidence estimator, the output shows that for hypothetical values of PrevH = 0.15 and I = 0.0175, midway in the step between 10 and 20% and 1.5 and 2% respectively, the necessary sample size for RSE_I = 0.25 is 2547 persons enrolled.</p>
-<p>Finally, for calculating the RSE of incidence over a range of 5 values of prevalence of positivity with a sample size of 5000, the user will set the sample size parameter to a given value, here <code>n = 5000</code>. The precision is set to output with option <code>RSE_I = &quot;out&quot;</code>.</p>
+<p>To calculate the RSE of incidence over a range of 5 values of prevalence of positivity, at a sample size of 5000:</p>
 <div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">incprecision</span>(<span class="dt">I =</span> <span class="fl">0.017</span>, <span class="dt">RSE_I =</span> <span class="st">'out'</span>, <span class="dt">PrevH =</span> <span class="kw">c</span>(<span class="fl">0.10</span>,<span class="fl">0.20</span>), <span class="dt">CR =</span> <span class="dv">1</span>, <span class="dt">MDRI =</span> <span class="dv">211</span>,
              <span class="dt">RSE_MDRI =</span> <span class="fl">0.05</span>, <span class="dt">FRR =</span> <span class="fl">0.009</span>, <span class="dt">RSE_FRR =</span> <span class="fl">0.2</span>, <span class="dt">BigT =</span> <span class="dv">720</span>, <span class="dt">n =</span> <span class="dv">5000</span>,
              <span class="dt">step =</span> <span class="dv">5</span>)</code></pre></div>
@@ -274,51 +271,6 @@ <h3>Examples</h3>
 ## 3  PrevH = 0.15   0.02113
 ## 4 PrevH = 0.175   0.02479
 ## 5   PrevH = 0.2   0.02845</code></pre>
-<!-- #not-for-release -->
-<!--
-If one study has already been completed, one may calculate sample size requirements for a second survey, to obtain desired power:
-
-* `n1` is set to the sample size of the completed  The function call for this situation is similar to the previous call, except the survey for which the sample size generation is to be performed will have the sample size parameter in the function call specified as `"out`. See below for an example of this syntax and output. Again, note that the function parameter for sample size is still set to `SS = "out"`.
-
-
-```r
-incpower(I1 = 0.05, I2 = 0.03, PrevH1 = 0.20, PrevH2 = 0.15, n1 = 5000,
-        n2 = "out", alpha = 0.05, Power = 0.8, SS = "out", CR = 1, DE_H = 1,
-        DE_R = 1, BMest = "same.test", MDRI = 200, RSE_MDRI = 0.05, FRR = 0.01,
-        RSE_FRR = 0.21, BigT = 730)
-```
-
-```
-## $Minimum.SS
-## [1] 3110
-## 
-## $Inc.Difference.Statistics
-##   deltaI_Est RSE_deltaI RSE_deltaI.infSS Power Power.infSS CI.low CI.up
-## 1       0.02      0.357            0.052   0.8       >0.99  0.006 0.034
-## 
-## $Implied.Incidence.Statistics
-##   Survey Given.I RSE_I CI.low CI.up
-## 1      1    0.05 0.115  0.039 0.061
-## 2      2    0.03 0.171  0.020 0.040
-## 
-## $Implied.MDRI.Statistics
-##   Given.MDRI CI.low CI.up
-## 1        200  180.4 219.6
-## 
-## $Implied.FRR.Statistics
-##   Given.FRR CI.low  CI.up
-## 1      0.01 0.0059 0.0141
-## 
-## $Implied.Subject.Counts
-##                            Survey.1 Survey.2
-## HIV.negative                   4000     2644
-## HIV.positive                   1000      466
-## HIV.post.tested.for.recent     1000      466
-## Recency.test.pos                116       47
-```
-The function now returns the necessary sample size for survey 2 that will generate power of 80\%, given the hypothetical population parameters for survey 2 and the observed parameter estimates for survey 1 and the assay characteristics MDRI, FRR, and their respective relative standard errors and time cut point T.
-
--->
 </div>
 </div>