Curtailed RRT

Input

curtailed_rrt() accepts/requires the following arguments:

str(formals(curtailed_rrt))

Dotted pair list of 8
 $ pi0  : symbol 
 $ pi1  : symbol 
 $ alpha: num 0.05
 $ power: NULL
 $ nMax : NULL
 $ model: symbol 
 $ p    : symbol 
 $ q    : NULL

Either power or nMax must be specified in the function call. If power is specified, the function computes the required maximum sample size and threshold values of the sequential procedure for the required error probabilities. Threshold values will be given in terms of number of affirmative responses (c) required to accept \(\mathcal{H}_1\) as well as the number of negative responses (\(N_{max} - c + 1\)) required to accept \(\mathcal{H}_0\).

Note that the probability distribution of observed data is discrete (i.e., a binomial distribution), hence, the specified error rates (alpha and 1 – power) typically cannot be satisfied exactly. However, rather than assuming normal approximation, curtailed_rrt() computes the smallest possible \(N_{max}\) and \(c\) such that the resulting curtailed procedure has exact error probabilities closest to, but never larger than the specified probabilities.

This computation is based on a numerical search algorithm which searches for the optimal parameters in a specified interval. By default, this interval is defined as \([1; 1,000,000]\). If the required maximum sample size is outside of this interval, the function will return NaN for the relevant parameters. The range of the search space can be adjusted in the curtailed_rrt.R script, but as this will hardly be of practical interest, it was not included as an argument in the main function.

Output

curtailed_rrt() returns a list of class c_rrt with the following components:

Printing

Next to the main function, the script defines generic print and plot functions for objects of class c_rrt. Thus, printing the output of curtailed_rrt() will return a user-friendly overview of the results. See the following examples for details on the function:

Example 1: Compute nMax and c to reach certain level of power (in UQM)

ex1_uqm <- curtailed_rrt(pi0 = .05, pi1 = .15, alpha = .05, power = .9, nMax = NULL,
                         model = "UQM", p = .75, q = .7)
ex1_uqm # same as print(ex1_uqm)

Curtailed RRT Design: Unrelated Question Model

Hypotheses on sensitive prevalence:
H0: pi = 0.05
H1: pi = 0.15
Randomization probability p = 0.75
Neutral prevalence q = 0.7
Maximum number of observations: N =  290
Decision thresholds:
H1: No of affirmative responses    H0: No of negative responses 
                             74                             217 
Resulting error rates:
Type I error        Power 
       0.046        0.901 

Example 2: Compute power for a given nMax (in CWM)

ex2_cwm <- curtailed_rrt(pi0 = .1, pi1 = .3, alpha = .05, power = NULL, nMax = 400,
                         model = "CWM", p = 2/3)
ex2_cwm

Curtailed RRT Design: Crosswise Model

Hypotheses on sensitive prevalence:
H0: pi = 0.1
H1: pi = 0.3
Randomization probability p = 0.67
Maximum number of observations: N =  400
Decision thresholds:
H1: No of affirmative responses    H0: No of negative responses 
                            164                             237 
Resulting error rates:
Type I error        Power 
       0.041        0.839 

Plotting

The object returned by curtailed_rrt() can also be passed on to the plot() function. This will, by default, return the Operating-Characteristic (OC) and the Average-Sample-Number (ASN) function. When plotting an object returned by curtailed_rrt(), the function accepts two additional arguments:

str(formals(plot.c_rrt))

Dotted pair list of 3
 $ x  : symbol 
 $ asn: logi TRUE
 $ oc : logi TRUE

Both oc and asn are TRUE by default. By setting one of {oc; asn} to FALSE, the function will only plot the other one. Note that specifying one argument as TRUE without explicitly setting the other as FALSE wil always return both plots.

Example 3: Plot OC and ASN function for Example 1

plot(ex1_uqm)

Example 4: Plot either OC or ASN function for Example 2

plot(ex2_cwm, oc = TRUE) # will return both

plot(ex2_cwm, asn = FALSE) # only return OC function

plot(ex2_cwm, oc = FALSE) # only return ASN function

Input

curtailed_rrt_result() accepts/requires the following arguments:

str(formals(curtailed_rrt_result))

Dotted pair list of 4
 $ plan      : symbol 
 $ data      : NULL
 $ N         : NULL
 $ conf.level: num 0.95

Either data or N must be specified in the function call. Calculations of the decision, subsequent estimate including standard error and confidence interval are possible based on both specifications. For a plotable output object, data must be specified.

If N is specified, exactly one decision bound must have been reached. Calculations based on N are not possible if less or more data than necessary have been collected. If more data than necessary were collected, provide data argument instead.

If data is specified, at least one decision bound must have been reached. Calculations based on data are not possible if less data than necessary have been collected. If more data than necessary have been collected the results will be based on the data available, when the first bound was reached. In this case curtailed_rrt_result() returns a warning.

Output

curtailed_rrt_result() returns a list of class c_rrt_result with the following components:

Printing

Next to the main function, the script curtailed_rrt_result.R defines generic print and plot functions for objects of class c_rrt_result. Thus, printing the output of curtailed_rrt_result() will return a user-friendly overview of the results. See the following examples for details on the function:

Example 8: Compute results based on raw data (using the sampling plan created in Example 1)

dat <- rbinom(300,1,0.4)
ex5_res_dat <- curtailed_rrt_result(plan = ex1_uqm, data = dat)

Warning in curtailed_rrt_result(plan = ex1_uqm, data = dat): More than necessary data collected.
  Results are based on the data when the first bound was reached.

ex5_res_dat 

Curtailed RRT Design: Unrelated Question Model

Hypotheses on sensitive prevalence:
H0: pi = 0.05
H1: pi = 0.15
Randomization probability p = 0.75
Neutral prevalence q = 0.7
Maximum number of observations: N =  290
Decision thresholds:
H1: No of affirmative responses    H0: No of negative responses 
                             74                             217 
Resulting error rates:
Type I error        Power 
       0.046        0.901 
Observed responses when reaching the first bound:
  Yes    No Total 
   74    96   170 

Decision:
Bound c of 74 affirmative responses was reached. Reject H0!

Subsequent estimate:  0.343 
Clopper-Pearson  95 % confidence interval:  0.249  to  0.447 

Note the warning indicating that dat contains more data than necessary. The results are based on the data available in the moment when the first bound (here c) was reached.

Example 9: Compute results based on N (using the sampling plan created in Example 1)

exN <- c(74,109)
ex6_res_N <- curtailed_rrt_result(plan = ex1_uqm, N = exN, conf.level = .90)
ex6_res_N 

Curtailed RRT Design: Unrelated Question Model

Hypotheses on sensitive prevalence:
H0: pi = 0.05
H1: pi = 0.15
Randomization probability p = 0.75
Neutral prevalence q = 0.7
Maximum number of observations: N =  290
Decision thresholds:
H1: No of affirmative responses    H0: No of negative responses 
                             74                             217 
Resulting error rates:
Type I error        Power 
       0.046        0.901 
Observed responses when reaching the first bound:
  Yes    No Total 
   74   109   183 

Decision:
Bound c of 74 affirmative responses was reached. Reject H0!

Subsequent estimate:  0.301 
Clopper-Pearson  90 % confidence interval:  0.224  to  0.387 

Note that the confidence level was changed from the default (95%) to 90%.

Plotting

The object returned by curtailed_rrt_result() can also be passed on to the plot() function. However, a plot can only be returned if the object was created using the data argument.

Example 10: Plot the results created in Example 8 (using raw data)

plot(ex5_res_dat)

Example 11: Plot the results created in Example 9 (using N)

plot(ex6_res_N) # will return an error

Error in plot.c_rrt_result(ex6_res_N): c_rrt_result object does not contain data to be plotted.