binGroup (version 2.2-1)

Inf.Array: Find the optimal testing configuration for informative array testing without master pooling

Description

Find the optimal testing configuration (OTC) for informative array testing without master pooling and calculate the associated operating characteristics.

Usage

Inf.Array(p, Se, Sp, group.sz, obj.fn, weights = NULL, alpha = 2)

Arguments

p

the probability of disease, which can be specified as an overall probability of disease, from which a heterogeneous vector of individual probabilities will be generated, or a heterogeneous vector of individual probabilities specified by the user.

Se

the sensitivity of the diagnostic test.

Sp

the specificity of the diagnostic test.

group.sz

a single group size (representing the row/column size) for which to calculate the operating characteristics, or a range of group (row/column) sizes over which to find the OTC.

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 scale parameter for the beta distribution that specifies the degree of heterogeneity for the generated probability vector. If a heterogeneous vector of individual probabilities is specified by the user, alpha can be specified as NA or will be ignored.

Value

A list containing:

prob

the probability of disease, as specified by the user.

alpha

the level of heterogeneity used to generate the vector of individual probabilities.

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 include:

Array.dim

the row/column size for the first stage of testing.

Array.sz

the overall array size (the square of the row/column size).

p.mat

the sorted matrix of individual probabilities, arranged using the gradient method described by McMahan et al. (2012).

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'.

Details

This function finds the OTC and computes the associated operating characteristics for informative array testing without master pooling, implemented using the gradient arrangement described in McMahan et al. (2012). Array testing without master pooling involves amalgamating specimens in rows and columns for the first stage of testing. This function uses only square arrays, which is the way array-based group testing is carried out in most real-world applications. Operating characteristics calculated are expected number of tests, pooling sensitivity, pooling specificity, pooling positive predictive value, and pooling negative predictive value for the algorithm. See Hitt et al. (2018) or McMahan et al. (2012) at http://chrisbilder.com/grouptesting for additional details on the implementaion of informative array testing without master pooling.

The value(s) specified by group.sz represent the initial group (row/column) size. If a single value is provided for group.sz, operating characteristics will be calculated and no optimization will be performed. 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).

References

Altman1994abinGroup

Altman1994bbinGroup

Graff1972binGroup

Hitt2018binGroup

Malinovsky2016binGroup

McMahan2012bbinGroup

See Also

NI.Array for non-informative array testing without master pooling, NI.A2M for non-informative array testing with master pooling, and OTC for finding the optimal testing configuration for a number of standard group testing algorithms.

http://chrisbilder.com/grouptesting

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

Examples

# NOT RUN {
# Find the OTC for informative array testing without 
#   master pooling over a range of group (row/column) sizes.
# 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. 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 examples 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)
Inf.Array(p=0.03, Se=0.99, Sp=0.99, group.sz=3:20, 
obj.fn=c("ET", "MAR"), alpha=2)
# }
# NOT RUN {
# 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.
set.seed(1002)
Inf.Array(p=0.03, Se=0.99, Sp=0.99, group.sz=3:5, 
obj.fn=c("ET", "MAR"), alpha=2)

# Find the OTC for a specified group (row/column) size 
#   for 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.
set.seed(14849)
Inf.Array(p=p.vec.func(p=0.05, alpha=0.5, grp.sz=100), 
Se=0.95, Sp=0.95, group.sz=10, obj.fn=c("ET", "MAR", "GR"),
weights=matrix(data=c(1,1,10,10), nrow=2, ncol=2, byrow=TRUE),
alpha=NA)
# }