VEwaningVariant (version 1.4)

veWaningVariant: Estimation of Vaccine Efficacy Over Time - Variant Aware

Description

Implements methods for inference on potential waning of vaccine efficacy and for estimation of vaccine efficacy at a user-specified time after vaccination based on data from a randomized, double-blind, placebo-controlled vaccine trial in which participants may be unblinded and placebo subjects may be crossed over to the study vaccine. The method allows for variant specification and adjustment for possible confounding via inverse probability weighting through specification of models for the trial entry process, unblinding mechanisms, censoring process, and the probability an unblinded placebo participant accepts study vaccine.

Usage

veWaningVariant(
  data,
  L,
  ...,
  phase = "ub",
  cutoff = 0.1,
  lag = 6,
  modelEntry = NULL,
  modelUnblind0 = NULL,
  modelUnblind1 = NULL,
  modelPsi = NULL,
  modelCensor0 = NULL,
  modelCensor1 = NULL,
  gFunc = NULL,
  variant = 0L,
  v = NULL,
  minWgt = NULL,
  maxWgt = NULL,
  txName = "A",
  U = "U",
  entryTime = "E",
  Gamma = "Gam",
  R = "R",
  Psi = "Psi",
  Delta = "Delta"
)

Value

A an S3 object of class "VEwaningVariant", which comprises a list object containing

theta

A vector object containing the estimated theta parameters.

cov

The covariance estimated using the sandwich estimator.

SE

The standard error estimated using the sandwich estimator.

and attributes "gFunc", "maxTime", "v", "phaseType", and "wgtType", which store details of the original analysis that are required for post-processing convenience functions ve() and plot(). See details for further information.

Arguments

data

A data.frame object containing all relevant data. Records with missing data will be removed prior to initiating the analysis.

L

A numeric object. The analysis time.

...

Ignored. Used only to require named inputs.

phase

A character object. The phase(s) to include in the analysis. Default is ="ub", indicating that both blinded and unblinded phases will be used to estimate theta values if possible. If ="b", only the blinded phase will be used. If ="u", only the unblinded phase will be used.

cutoff

A numeric object. The minimum proportion of infections that must occur during a phase to be included in the analysis. The default is 0.1 (10 blinded (unblinded) phase, only the unblinded (blinded) phase will be included in the analysis.

lag

A scalar numeric, numeric vector, or character object. The lag time(s) between the initial vaccine dose and full efficacy. If a scalar, the provided lag time applies to all participants. If a numeric vector, the vector contains the individual specific lag time for each participant (see details for further information). If character, the column header of the data containing the lag times. The default value is a scalar value of 6 weeks (42 days) -- NOTE this assumes that the data are on the scale of weeks.

modelEntry

A formula object or NULL. The coxph model for entry times. The LHS is set as the appropriate Surv() object internally. If a LHS is provided, it is ignored. If NULL, inputs modelPsi, modelUnblind0, and modelUnblind1 must also be NULL. See Details for further information.

modelUnblind0

A formula object or NULL. The coxph model for unblinding/crossover for placebo (A=0) participants. If NULL, inputs modelEntry, modelPsi, and modelUnblind1 must also be NULL. See Details for further information.

modelUnblind1

A formula object or NULL. The coxph model for unblinding for vaccinated (A=1) participants. If NULL, inputs modelEntry, modelPsi, and modelUnblind0 must also be NULL. See Details for further information.

modelPsi

A formula object or NULL. The logistic model for the probability that a placebo participant (A = 0) is unblinded at R (Gamma = 1) and agrees to take the study vaccine (Psi = 1). If a LHS is provided, it is ignored. If NULL, inputs modelEntry, modelUnblind0, and modelUnblind1 must also be NULL. See Details for further information.

modelCensor0

A formula object or NULL. The coxph model for censoring for placebo (A=0) participants. The LHS is set as the appropriate Surv() object internally. If a LHS is provided, it is ignored. If NULL, all other models must be NULL. See Details for further information.

modelCensor1

A formula object or NULL. The coxph model for censoring for vaccinated (A=1) participants. The LHS is set as the appropriate Surv() object internally. If a LHS is provided, it is ignored. If NULL, all other models must be NULL. See Details for further information.

gFunc

A character vector object. The model of infection rates. Must be one of {'lin', 'piece', 'splin', 'spcub'} for the linear, piecewise constant, linear spline, and cubic spline models, respectively.

variant

An integer object. The variant for the analysis. If 0, all variants are included in the analysis.

v

A numeric vector object. The knots or cut-offs to be used for input gFunc. If gFunc = 'lin', this input is ignored. For 'splin' and 'spcub', the knots of the spline on (0,L). For 'piece', the cut-offs on (0,L). Note that this input should not include the extremes 0 and L.

minWgt

A numeric object. If not NULL, the minimum non-zero value a weight can have, i.e., weight = max(minWgt, weight). If NULL, no lower truncation of weights is performed.

maxWgt

A numeric object. If not NULL, the maximum value a weight can have, i.e., weight = min(maxWgt, weight). If NULL, no upper truncation of weights is performed.

txName

A character object. The header of the column of data containing the treatment variable. Default value is 'A'. Treatment must be coded as 0/1, where 1 indicates that participant was vaccinated; 0 otherwise.

U

A character object. The header of the column of data containing the minimum of time to infection, time to refusing study vaccine after unblinding (placebo participants only), or time to censoring (due to loss to follow up or administrative censoring).

entryTime

A character object. The header of the column of data containing the time of entry into the study on the scale of the calendar time. Default value is 'E'.

Gamma

A character object. The header of the column of data containing the category for the R dynamic. Default value is 'Gam'. Data must be 0/1, where 1 indicates that R is the time to unblinding; 0 indicates that R is the infection time or the censoring time.

R

A character object. The header of the column of data containing the minimum of: time to unblinding, time to infection, or time to censoring.

Psi

A character object. The header of the column of data containing the indicator of whether a participant received study vaccine, where 1 indicates that a participant was assigned to placebo is unblinded and decides to get the study vaccine or that a participant was assigned to vaccine; 0 otherwise. Default value is 'Psi'.

Delta

A character object. The header of the column of data containing the infection-variant category indicator.

Details

Analysis data must include the following information:

E

The study entry time.

A

Binary treatment assignment, where A=0 indicates placebo; A = 1 otherwise.

U

The minimum of: time to infection, time to refusing study vaccine after unblinding (placebo participants only), or time to censoring (loss to followup or administrative censoring due to analysis at time L).

Delta

Infection-variant category indicator, where: -1 indicates a placebo participant was unblinded and refused study vaccine; 0 indicates censoring; and = ve indicates infection of variant ve (ve = 1, ..., nV).

R

The minimum of: time to unblinding, time to infection, or time to censoring.

Gamma

Indicator of R dynamic, where 1 indicates that R is the time to unblinding and 0 indicates that R is either the time to infection or the time to censoring.

Psi

Indicator of whether a subject received study vaccine, where 1 indicates that a participant was assigned to vaccine or was assigned to placebo is unblinded and decides to get the study vaccine; 0 otherwise.

Data can include baseline covariates. Methods for time-dependent covariates are not currently available.

If input lag is provided as a numeric vector or as a column of the data, lag values should be set to Inf or NA for participants that do not reach full efficacy.

There are 3 possible weighting options, the selection of which is determined by the combination of model inputs.

No weighting:

No models are provided as input, i.e., inputs modelEntry, modelUnblind0, modelUnblind1, modelPsi, modelCensor0, and modelCensor1 are not provided or are NULL.

Weighting depends only on the censoring dynamic:

Models modelCensor0 and modelCensor1 must be provided and models modelEntry, modelUnblind0, modelUnblind1, modelPsi must be NULL.

Weighting depends on the entry, unblinding, and censoring dynamics:

All models must be provided.

The returned S3 object has 6 attributes needed for post-processing tools ve() and plot(). Specifically, "gFunc" is an integer object specifying the model selected for the infection rate (based on input gFunc); "v", the knots or cut-offs to be used by gFunc (input v); "maxTime", the maximum time since full efficacy included in the analysis; "phaseType", =1 only unblinded phase, =2, only blinded phase, =3 both phases, and "wgtType", =0 no weighting, =1 censor weighting, =2 full weighting.

Examples

# \dontshow{
  RcppArmadillo::armadillo_throttle_cores(2)
# }
data(variantData)

set.seed(1234)

ind <- sample(1:nrow(variantData), 2000)
# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.

# no weighting -- variant 1 infection only

res_noWgt <- veWaningVariant(data = variantData[ind,], 
                             L = 52.0,  
                             variant = 1L,
                             gFunc = 'piece', 
                             v = c(5.0,10.0))

# censoring only weighting -- variant 1 infection only

res_cens <- veWaningVariant(data = variantData[ind,], 
                            L = 52.0,  
                            variant = 1L,
                            modelCensor0 = ~ X1+X2, 
                            modelCensor1 = ~ X1+X2, 
                            gFunc = 'piece', 
                            v = c(5.0,10.0))

# full weighting -- variant 1 infection only

if (FALSE) res_full <- veWaningVariant(data = variantData[ind,], 
                            L = 52.0,  
                            variant = 1L,
                            modelEntry = ~ X1,
                            modelUnblind0 = ~X1+X2,
                            modelUnblind1 = ~X2,
                            modelPsi = ~X1*X2,
                            modelCensor0 = ~ X1+X2, 
                            modelCensor1 = ~ X1+X2, 
                            gFunc = 'piece', 
                            v = c(5.0,10.0))