OTC: Find the optimal testing configuration
In binGroup: Evaluation and Experimental Design for Binomial Group Testing

Description Usage Arguments Details Value Author(s) References See Also Examples

Find the optimal testing configuration (OTC) for standard group testing algorithms and calculate the associated operating characteristics.

1 2	OTC(algorithm, p = NULL, probabilities = NULL, Se = 0.99, Sp = 0.99, group.sz, obj.fn = c("ET", "MAR"), weights = NULL, alpha = 2)

`algorithm`	character string defining the group testing algorithm to be used. Non-informative testing options include two-stage hierarchical ("`D2`"), three-stage hierarchical ("`D3`"), square array testing without master pooling ("`A2`"), and square array testing without master pooling ("`A2M`"). Informative testing options include two-stage hierarchical ("`ID2`"), three-stage hierarchical ("`ID3`"), and square array testing without master pooling ("`IA2`").
`p`	overall probability of disease that will be used to generate a vector/matrix of individual probabilities. For non-informative algorithms, a homogeneous set of probabilities will be used. For informative algorithms, the `p.vec.func` function will be used to generate a heterogeneous set of probabilities. Either `p` or `probabilities` should be specified, but not both.
`probabilities`	a vector of individual probabilities, which is homogeneous for non-informative testing algorithms and heterogeneous for informative testing algorithms. Either `p` or `probabilities` should be specified, but not both.
`Se`	the sensitivity of the diagnostic test.
`Sp`	the specificity of the diagnostic test.
`group.sz`	a single group size or range of group sizes for which to calculate operating characteristics and/or find the OTC. The details of group size specification are given under 'Details'.
`obj.fn`	a list of objective functions which are minimized to find the OTC. The expected number of tests per individual, "`ET`", will always be calculated. Additional options include "`MAR`" (the expected number of tests divided by the expected number of correct classifications, described in Malinovsky et al. (2016)), and "`GR`" (a linear combination of the expected number of tests, the number of misclassified negatives, and the number of misclassified positives, described in Graff & Roeloffs (1972)). See Hitt et al. (2018) at http://chrisbilder.com/grouptesting for additional details.
`weights`	a matrix of up to six sets of weights for the GR function. Each set of weights is specified by a row of the matrix.
`alpha`	a shape parameter for the beta distribution that specifies the degree of heterogeneity for the generated probability vector (for informative testing only).

This function finds the OTC and computes the associated operating characteristics for standard group testing algorithms, as described in Hitt et al. (2018) at http://chrisbilder.com/grouptesting.

Available algorithms include two- and three-stage hierarchical testing and array testing with and without master pooling. Both non-informative and informative group testing settings are allowed for each algorithm, except informative array testing with master pooling is unavailable because this method has not appeared in the group testing literature. Operating characteristics calculated are expected number of tests, pooling sensitivity, pooling specificity, pooling positive predictive value, and pooling negative predictive value for each individual.

The value(s) specified by group.sz represent the initial (stage 1) group size for three-stage hierarchical testing and non-informative two-stage hierarchical testing. For informative two-stage hierarchical testing, the group.sz specified represents the block size used in the pool-specific optimal Dorfman (PSOD) method, where the initial group (block) is not tested. For more details on informative two-stage hierarchical testing implemented via the PSOD method, see Hitt et al. (2018) and McMahan et al. (2012a). For array testing without master pooling, the group.sz specified represents the row/column size for initial (stage 1) testing. For array testing with master pooling, the group.sz specified represents the row/column size for stage 2 testing. The group size for initial testing is overall array size, given by the square of the row/column size.

If a single value is provided for group.sz with array testing or non-informative two-stage hierarchical testing, operating characteristics will be calculated and no optimization will be performed. If a single value is provided for group.sz with three-stage hierarchical or informative two-stage hierarchical, the OTC will be found over all possible configurations. If a range of group sizes is specified, the OTC will be found over all group sizes.

The displayed pooling sensitivity, pooling specificity, pooling positive predictive value, and pooling negative predictive value are weighted averages of the corresponding individual accuracy measures for all individuals within the initial group for a hierarchical algorithm, or within the entire array for an array-based algorithm. Expressions for these averages are provided in the Supplementary Material for Hitt et al. (2018). These expressions are based on accuracy definitions given by Altman and Bland (1994a, 1994b).

A list containing:

`prob`	the probability of disease, as specified by the user.
`alpha`	level of heterogeneity for the generated probability vector (for informative testing only).
`Se`	the sensitivity of the diagnostic test.
`Sp`	the specificity of the diagnostic test.
`opt.ET, opt.MAR, opt.GR`	a list for each objective function specified by the user, containing: OTC a list specifying elements of the optimal testing configuration, which may include: Stage1 pool size for the first stage of hierarchical testing, if applicable. Stage2 pool sizes for the second stage of hierarchical testing, if applicable. Block.sz the block size/initial group size for informative Dorfman testing, which is not tested. pool.szs pool sizes for the first stage of testing for informative Dorfman testing. Array.dim the row/column size for array testing. Array.sz the overall array size for array testing (the square of the row/column size). p.vec the sorted vector of individual probabilities, if applicable. p.mat the sorted matrix of individual probabilities in gradient arrangement, if applicable. ET the expected testing expenditure for the OTC. value the value of the objective function per individual. PSe the overall pooling sensitivity for the algorithm. Further details are given under 'Details'. PSp the overall pooling specificity for the algorithm. Further details are given under 'Details'. PPPV the overall pooling positive predictive value for the algorithm. Further details are given under 'Details'. PNPV the overall pooling negative predictive value for the algorithm. Further details are given under 'Details'.

Brianna D. Hitt

\insertRef

Altman1994abinGroup

\insertRef

Altman1994bbinGroup

\insertRef

Graff1972binGroup

\insertRef

Hitt2018binGroup

\insertRef

Malinovsky2016binGroup

\insertRef

McMahan2012abinGroup

\insertRef

McMahan2012bbinGroup

NI.Dorf for non-informative two-stage (Dorfman) testing, Inf.Dorf for informative two-stage (Dorfman) testing, NI.D3 for non-informative three-stage hierarchical testing, Inf.D3 for informative three-stage hierarchical testing, NI.Array for non-informative array testing, Inf.Array for informative array testing, and NI.A2M for non-informative array testing with master pooling.

http://chrisbilder.com/grouptesting

Other OTC functions: Inf.Array, Inf.D3, Inf.Dorf, NI.A2M, NI.Array, NI.D3, NI.Dorf

# Find the OTC for non-informative
#   two-stage hierarchical (Dorfman) testing
# This example takes less than 1 second to run.
# Estimated running time was calculated using a 
#   computer with 16 GB of RAM and one core of an 
#   Intel i7-6500U processor.
OTC(algorithm="D2", p=0.05, Se=0.99, Sp=0.99, group.sz=2:100,
obj.fn=c("ET", "MAR"))

# Find the OTC for informative
#   two-stage hierarchical (Dorfman) testing, implemented
#   via the pool-specific optimal Dorfman (PSOD) method
#   described in McMahan et al. (2012a), where the greedy
#   algorithm proposed for PSOD is replaced by considering
#   all possible testing configurations.
# A vector of individual probabilities is generated using
#   the expected value of order statistics from a beta 
#   distribution with p = 0.01 and a heterogeneity level 
#   of alpha = 0.5. Depending on the specified probability, 
#   alpha level, and overall group size, simulation may 
#   be necessary in order to generate the vector of individual
#   probabilities. This is done using p.vec.func() and 
#   requires the user to set a seed in order to reproduce 
#   results.
# This example takes approximately 2.5 minutes to run.
# Estimated running time was calculated using a 
#   computer with 16 GB of RAM and one core of an 
#   Intel i7-6500U processor.
## Not run: 
set.seed(52613)
OTC(algorithm="ID2", p=0.01, Se=0.95, Sp=0.95, group.sz=50,
obj.fn=c("ET", "MAR", "GR"),
weights=matrix(data=c(1, 1, 10, 10, 0.5, 0.5), 
nrow=3, ncol=2, byrow=TRUE), alpha=0.5)
## End(Not run)

# Find the OTC over all possible
#   testing configurations for a specified group size for
#   non-informative three-stage hierarchical testing
# This example takes approximately 1 second to run.
# Estimated running time was calculated using a 
#   computer with 16 GB of RAM and one core of an 
#   Intel i7-6500U processor.
OTC(algorithm="D3", p=0.001, Se=0.95, Sp=0.95, group.sz=18,
obj.fn=c("ET", "MAR", "GR"),
weights=matrix(data=c(1, 1), nrow=1, ncol=2, byrow=TRUE))

# Find the OTC for non-informative
#   three-stage hierarchical testing
# This example takes approximately 20 seconds to run.
# Estimated running time was calculated using a 
#   computer with 16 GB of RAM and one core of an 
#   Intel i7-6500U processor.
## Not run: 
OTC(algorithm="D3", p=0.06, Se=0.90, Sp=0.90, 
group.sz=3:30, obj.fn=c("ET", "MAR", "GR"),
weights=matrix(data=c(1, 1, 10, 10, 100, 100), 
nrow=3, ncol=2, byrow=TRUE))
## End(Not run)

# Find the OTC over all possible configurations 
#   for a specified group size, given a 
#   heterogeneous vector of probabilities.
# This example takes less than 1 second to run.
# Estimated running time was calculated using a 
#   computer with 16 GB of RAM and one core of an 
#   Intel i7-6500U processor.
OTC(algorithm="ID3", probabilities=c(0.012, 0.014, 0.011, 
0.012, 0.010, 0.015), Se=0.99, Sp=0.99, group.sz=6, 
obj.fn=c("ET","MAR","GR"), weights=matrix(data=c(1, 1), 
nrow=1, ncol=2, byrow=TRUE), alpha=0.5)

# Calculate the operating characteristics for a specified array size
#   for non-informative array testing without master pooling
# This example takes less than 1 second to run.
# Estimated running time was calculated using a 
#   computer with 16 GB of RAM and one core of an 
#   Intel i7-6500U processor.
OTC(algorithm="A2", p=0.005, Se=0.95, Sp=0.95, group.sz=8, 
obj.fn=c("ET", "MAR"))

# Find the OTC for informative array testing without 
#   master pooling
# A vector of individual probabilities is generated using
#   the expected value of order statistics from a beta 
#   distribution with p = 0.03 and a heterogeneity level 
#   of alpha = 2. The probabilities are then arranged in 
#   a matrix using the gradient method described in 
#   McMahan et al. (2012b). Depending on the specified 
#   probability, alpha level, and overall group size, 
#   simulation may be necessary in order to generate the 
#   vector of individual probabilities. This is done using 
#   p.vec.func() and requires the user to set a 
#   seed in order to reproduce results.
# This example takes approximately 30 seconds to run.
# Estimated running time was calculated using a 
#   computer with 16 GB of RAM and one core of an 
#   Intel i7-6500U processor.
## Not run: 
set.seed(1002)
OTC(algorithm="IA2", p=0.03, Se=0.95, Sp=0.95, 
group.sz=3:20, obj.fn=c("ET", "MAR", "GR"),
weights=matrix(data=c(1, 1, 10, 10, 100, 100), 
nrow=3, ncol=2, byrow=TRUE), alpha=2)
## End(Not run)

# Find the OTC for non-informative array testing 
#   with master pooling
# This example takes approximately 20 seconds to run.
# Estimated running time was calculated using a 
#   computer with 16 GB of RAM and one core of an 
#   Intel i7-6500U processor.
## Not run: 
OTC(algorithm="A2M", p=0.02, Se=0.90, Sp=0.90, 
group.sz=3:20, obj.fn=c("ET", "MAR", "GR"),
weights=matrix(data=c(1, 1, 10, 10, 0.5, 0.5, 2, 2, 
100, 100, 10, 100), nrow=6, ncol=2, byrow=TRUE))
## End(Not run)