gtreg.halving {binGroup}

Fitting Group Testing Models Under the Halving Protocol

Description

gtreg.halving is a function to fit the group testing regression model under the halving protocol specified through a symbolic description of the linear predictor and descriptions of the group testing setting.

Usage

gtreg.halving(formula, data, groupn, subg, retest, sens = 1,
 spec = 1, linkf = c("logit", "probit", "cloglog"),
 sens.ind = NULL, spec.ind = NULL, start = NULL, control = gt.control(...), ...)

EM.halving(Y, X, groupn, subg, ret, sens, spec, linkf, sens.ind,
 spec.ind, start = NULL, control = gt.control())

Arguments

formula

an object of class "formula" (or one that can be coerced to that class): a symbolic description of the model to be fitted. The details of model specification are given under 'Details'.

data

an optional data frame, list or environment (or object coercible by as.data.frame to a data frame) containing the variables in the model. If not found in data, the variables are taken from environment(formula), typically the environment from which gtreg.halving is called.

groupn

a vector, list or data frame of the group numbers that designates individuals to groups.

subg

a vector, list or data frame of the group numbers that designates individuals to subgroups.

retest

a vector, list or data frame of individual retest results within a subgroup that tests positive.

sens

sensitivity of the test, set to be 1 by default.

spec

specificity of the test, set to be 1 by default.

sens.ind

sensitivity of the individual retests, set to be equal to sens if not specified otherwise.

spec.ind

specificity of the individual retests, set to be equal to spec if not specified otherwise.

linkf

a character string specifying one of the three link functions for a binomial model: "logit" (default) or "probit" or "cloglog".

start

starting values for the parameters in the linear predictor.

control

a list of parameters for controlling the fitting process. See the documentation for gt.control for details.

Y

For EM.halving: the vector of the group responses.

X

For EM.halving: the design matrix of the covariates.

ret

For EM.halving: a vector containing individual retest results.

...

arguments to be passed by default to gt.control: see argument control

Details

A typical predictor has the form groupresp ~ covariates where response is the (numeric) group response vector and covariates is a series of terms which specifies a linear predictor for individual responses. Note that it is actually the unobserved individual responses, not the observed group responses, which are modeled by the covariates here. In groupresp, a 0 denotes a negative response and a 1 denotes a positive response, where the probability of an individual positive response is being modeled directly. A terms specification of the form first + second indicates all the terms in first together with all the terms in second with duplicates removed. The terms in the formula will be re-ordered so that main effects come first, followed by the interactions, all second-order, all third-order and so on; to avoid this pass a terms object as the formula.

A specification of the form first:second indicates the set of terms obtained by taking the interactions of all terms in first with all terms in second. The specification first*second indicates the cross of first and second. This is the same as first + second + first:second.

The EM.halving function apply Xie's EM algorithm to the likelihood function written in terms of the unobserved individual responses; the functions use glm.fit to update the parameter estimates within each M step. In the halving protocol, if the initial group tests positive, it is split into two subgroups. The two subgroups are subsequently tested and if either subgroup tests positive, the third and final step is to test all individuals within the subgroup. Thus, within subg, subgroup responses in observed positive groups are 0 (negative) or 1 (positive); the remaining subgroup responses are NAs meaning that no tests are performed for them. The individual retests are similarly coded.

Value

gtreg.halving returns an object of class "gt". See later in this section. The function summary (i.e., summary.gt) can be used to obtain or print a summary of the results. The group testing functions predict (i.e., predict.gt) and residuals (i.e., residuals.gt) can be used to extract various useful features of the value returned by gtreg.halving. An object of class "gt" is a list containing at least the following components:

coefficients

a named vector of coefficients

hessian

estimated Hessian matrix of the negative log likelihood function, serves as an estimate of the information matrix

residuals

the response residuals, difference of the observed group responses and the fitted group responses.

fitted.values

the fitted mean values of group responses.

deviance

the deviance between the fitted model and the saturated model.

aic

Akaike's An Information Criterion, minus twice the maximized log-likelihood plus twice the number of coefficients

counts

the number of iterations in the EM algorithm.

z

the vector of group responses.

call

the matched call.

formula

the formula supplied.

terms

the terms object used.

method

the method "Xie" used to fit the model.

link

the link function used in the model.

Author(s)

Boan Zhang

References

Xie, M. (2001), Regression analysis of group testing samples, Statistics in Medicine, 20, 1957-1969.

See Also

summary.gt, predict.gt and residuals.gt for gt methods.

Examples

## --- Continuing the Example from  '?sim.halving':

set.seed(46)
gt.data <- sim.halving(par = c(-6, .1), gshape = 17, gscale = 1.4,
               sample.size = 5000, group.size = 5,
               sens = 0.95, spec = 0.95)
fit1 <- gtreg.halving(formula = gres ~ x, data = gt.data, groupn = groupn,
        start = c(-6, .1), subg = subgroup, retest = retest,
        sens = .95, spec = .95, trace = TRUE)
summary(fit1)