permci_glm: Randomization-Based CI for regression

In djrabideau/permuter: Randomization tests and confidence intervals

Randomization-Based CI for regression

Description

Calculate a randomization-based confidence interval (CI) for a regression parameter from a particular regression model, see Details.

Usage

permci_glm(formula, trtname, runit, strat = NULL, family = gaussian,
  data, nperm = 1000, nburn = 0, level = 0.95, init,
  initmethod = "perm", ncores = 1, seed, quietly = F, method = "G",
  m, k, Ps = NULL, n)

permci_survreg(formula, trtname, runit, strat = NULL, data,
  dist = "weibull", nperm = 1000, nburn = 0, level = 0.95, init,
  initmethod = "perm", ncores = 1, seed, quietly = F, method = "G",
  m, k, Ps = NULL, n)

permci_coxph(formula, trtname, runit, strat = NULL, data, nperm = 1000,
  nburn = 0, level = 0.95, init, initmethod = "perm", ncores = 1,
  seed, quietly = F, method = "G", m, k, Ps = NULL, n)

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. This argument is passed to the corresponding regression function, e.g. glm (see Details).
trtname	character string specifying the name of randomized treatment variable in data (variable to permute)
runit	character string specifying the name of unit of randomization in data
strat	an optional character string specifying the name of the variable in data upon which randomization was stratified
family	a description of the error distribution and link function to be used in the model. This can be a character string naming a family function, a family function or the result of a call to a family function. (See family for details.)
data	a data frame containing the variables in the model. This argument is passed to the corresponding regression function, e.g. glm (see Details).
nperm	number of permutations for each randomization CI bound
nburn	number of “burn-in” permutations. I.e. algorithm will start at init bounds, run for nburn permutations, then restart algorithm at latest estimates from “burn-in” phase and run for another nperm permutations until the final CI estimates are reached. Increasing nburn may help convergence if init CI bounds are poor.
level	two-sided confidence level (e.g. level = 0.95 for 95% CI)
init	vector of initial values for CI, with lower bound as first element and upper bound as second. If init not provided, initial bounds are based on initmethod.
initmethod	character; indicates the method to be used for initial values for CI. If "asymp", initial bounds are based on asymptotic approximation (e.g. Wald CI for GLM). If "perm" (default), initial bounds are based on the permutation approach used in Garthwaite (1996) with \hat{\theta} \pm \{(t_2 - t_1)/2\}, where t_1 and t_2 denote the second smallest and second largest estimates from the permutation test.
ncores	number of cores to use for computation. If ncores > 1, lower and upper bound search procedures run in parallel across 2 cores.
seed	a numerical seed to use, passed to set.seed (if ncores == 1) or registerDoRNG (if ncores > 1).
quietly	logical; if TRUE (and if ncores == 1), status updates will be printed to Console otherwise, suppress updates.
method	if method = 'G' (default), then search is carried out as described in Garthwaite (1996). For longer searches (nperm >= 200,000), method = 'GJ' is recommended and carried out as outlined in Garthwaite and Jones (2009).
m	an optional initial magnitude of the steps; if left unspecified, m defaults to recommended value proposed in Garthwaite and Buckland (1992)
k	step length multiplier
Ps	if method = 'GJ', vector of search lengths for each phase (if unspecified, defaults to recommended values in Garthwaite and Jones (2009))
n	if method = 'GJ', the unweighted averages of the final n values are taken as the final CI (if unspecified, defaults to recommended value in Garthwaite and Jones (2009))
dist	assumed distribution for y variable. If the argument is a character string, then it is assumed to name an element from survreg.distributions. These include "weibull", "exponential", "gaussian", "logistic","lognormal" and "loglogistic". Otherwise, it is assumed to be a user defined list conforming to the format described in survreg.distributions.

Details

These functions are used to calculate randomization-based confidence intervals (CI) for a regression parameter. These CIs correspond to inverting randomization tests by using an offset to test non-zero "null" values (Rabideau and Wang). To invert the randomization test, these functions adapt a computationally efficient CI algorithm based on the Robbins-Monro search process. Two methods can be used and correspond to Garthwaite (1996) and Garthwaite and Jones (2009).

These functions corrrespond to particular regression models:

• permci_glm: randomization CI based on glm

• permci_survreg: randomization CI based on survreg

• permci_coxph: randomization CI based on coxph

To ensure correct specification of the parameters passed to the models above (e.g. formula in survreg), please refer to their documentation.

References

Garthwaite, P. H. (1996). Confidence intervals from randomization tests. Biometrics 52, 1387–1393.

Garthwaite, P. H. and Jones, M. C. (2009). A Stochastic Approximation Method and Its Application to Confidence Intervals. Journal of Computational and Graphical Statistics 18, 184-200.

Rabideau, D. J. and Wang, R. Randomization-Based Confidence Intervals for Cluster Randomized Trials. Under Review.

See Also

permci for a more general CI function; permci_glm, permci_survreg, permci_coxph for corresponding randomization-based CIs

Examples

# Calculate randomization-based CI for the incidence rate ratio (IRR) of
# bacterial pneumonia episodes between the two intervention groups in
# pneumovac data set. (Note, it will take a few seconds to run 1,000
# permutations)

head(pneumovac) # visualize data
ci <- permci_glm(bpepisodes ~ spnvac, trtname = 'spnvac',
                 runit = 'randunit', family = poisson, data = pneumovac,
                 nperm = 1000, ncores = 2, seed = 445)
print(ci$ci)
#       lower       upper
# -0.97314014  0.06265964
plot(ci) # monitor convergence of CI search

djrabideau/permuter documentation built on Jan. 9, 2025, 11:45 p.m.