gtSim {binGroup2}

Simulation function for group testing data

Description

Simulates data in group testing form ready to be fit by gtReg.

Usage

gtSim(
  type = "sp",
  x = NULL,
  gshape = 20,
  gscale = 2,
  par,
  linkf = c("logit", "probit", "cloglog"),
  size1,
  size2,
  sens = 1,
  spec = 1,
  sens.ind = NULL,
  spec.ind = NULL
)

Arguments

type

"sp" for simple pooling (Dorfman testing with or without retests), "halving" for halving protocol, and "array" for array testing (also known as matrix pooling).

x

a matrix of user-submitted covariates with which to simulate the data. Default is NULL, in which case a gamma distribution is used to generate the covariates automatically.

gshape

shape parameter for the gamma distribution. The value must be non-negative. Default value is set to 20.

gscale

scale parameter for the gamma distribution. The value must be strictly positive. Default value is set to 2.

par

the true coefficients in the linear predictor.

linkf

a character string specifying one of the three link functions to be used: "logit" (default), "probit", or "cloglog".

size1

sample size of the simulated data (for use with "sp" and "halving" methods) or a vector that specifies the number of rows in each matrix (for use with "array" method). If only one matrix is simulated, this value is a scalar.

size2

group size in pooling individual samples (for use with "sp" and "halving" methods) or a vector that specifies the number of columns in each matrix (for use with "array" method). If only one matrix is simulated, this value is a scalar.

sens

sensitivity of the group tests. Default value is set to 1.

spec

specificity of the group tests. Default value is set to 1.

sens.ind

sensitivity of the individual retests. If NULL, set to be equal to sens.

spec.ind

specificity of the individual retests. If NULL, set to be equal to spec.

Details

Generates group testing data in simple pooling form (type = "sp"), for the halving protocol (type = "halving"), or in array testing form (type = "array"). The covariates are either specified by the x argument or they are generated from a gamma distribution with the given gshape and gscale parameters. The individual probabilities are calculated from the covariates, the coefficients given in par, and the link function specified through linkf. The true binary individual responses are then simulated from the individual probabilities.

Under the matrix pooling protocol (type = "array"), the individuals are first organized into (by column) one or more matrices specified by the number of rows (size1) and the number of columns (size2).

Then, for all pooling protocols, the true group responses are found from the individual responses within groups or within rows/columns for matrix pooling (i.e., if at least one response is positive, the group is positive; otherwise, the group response is negative). Finally, the observed group (method = "sp") and subgroup method = "halving" only), or row and column responses method = "array" are simulated using the given sens and spec.

For the simple pooling and halving protocols, individual retests are simulated from sens.ind and spec.ind for samples in observed positive groups. Note that with a given group size (specified by size2 with method = "sp" or method = "halving"), the last group may have fewer individuals. For the matrix pooling protocol, individual retests are simulated from sens.ind and spec.ind for individuals that lie on the intersection of an observed positive row and and observed positive column. In the case where no column (row) tests positive in a matrix, all the individuals in any observed positive rows (columns) will be assigned a simulated retest result. If no column or row is observed positive, NULL is returned.

Value

For simple pooling (type = "sp") and the halving protocol (type = "halving"), a data frame or for array testing (type = "array"), a list, which may include the following:

gres

the group response, for simple pooling and the halving protocol only.

col.resp

the column group response, for array testing only.

row.resp

the row group response, for array testing only.

x

the covariate.

groupn

the group number, for simple pooling and the halving protocol only.

arrayn

the array number, for array testing only.

coln

the column group number, for array testing only.

rown

the row group number, for array testing only.

ind

the true individual responses. For simple pooling and the halving protocol, these are included in the data frame of results. For array testing, these are included in the list of results, with individual responses presented in matrices.

retest

the results of individual retests.

subgroup

the subgroup number, for the halving protocol.

prob

the individual probabilities, for array testing only.

Author(s)

This function is a combination of sim.gt, sim.halving, and sim.mp written by Boan Zhang for the binGroup package. Minor modifications have been made for inclusion of the functions in the binGroup2 package.

See Also

gtReg to fit simulated group testing data.

Examples

set.seed(46)
gt.data <- gtSim(type = "sp", par = c(-12, 0.2),
                 size1 = 700, size2 = 5)

x1 <- sort(runif(100, 0, 30))
x2 <- rgamma(100, shape = 17, scale = 1.5)
gt.data <- gtSim(type = "sp", x = cbind(x1, x2),
                 par = c(-14, 0.2, 0.3), size2 = 4,
                 sens = 0.98, spec = 0.98)

set.seed(46)
gt.data <- gtSim(type = "halving", par = c(-6, 0.1),
                 gshape = 17, gscale = 1.4, size1 = 5000,
                 size2 = 5, sens = 0.95, spec = 0.95)

# 5x6 and 4x5 matrix
set.seed(9128)
sa1a <- gtSim(type = "array", par = c(-7, 0.1),
              size1 = c(5, 4), size2 = c(6, 5),
              sens = 0.95, spec = 0.95)
sa1a$dframe