Package 'DOVE' reference manual

Title:	Durability of Vaccine Efficacy
Description:	Implements maximum likelihood methods for evaluating the durability of vaccine efficacy in a randomized, placebo-controlled clinical trial with staggered enrollment of participants and potential crossover of placebo recipients before the end of the trial. Lin, D. Y., Zeng, D., and Gilbert, P. B. (2021) <doi:10.1093/cid/ciab226> and Lin, D. Y., Gu, Y., Zeng, D., Janes, H. E., and Gilbert, P. B. (2021) <doi:10.1093/cid/ciab630>.
Authors:	Danyu Lin [aut], Yu Gu [aut], Donglin Zeng [aut], Shannon T. Holloway [aut, cre]
Maintainer:	Shannon T. Holloway <[email protected]>
License:	GPL-2
Version:	1.10
Built:	2024-11-10 04:16:06 UTC
Source:	https://github.com/cran/DOVE

Durability of Vaccine Efficacy

Description

Estimates the potentially waning long-term efficacy of vaccines in randomized, placebo-controlled clinical trials with staggered enrollment of participants and sequential crossover of placebo recipients. The hazard ratio for the vaccine effect is a nonparametric function of time.

Usage

dove(formula, data, plots = TRUE, timePts = NULL, bandwidth = NULL)
dove(formula, data, plots = TRUE, timePts = NULL, bandwidth = NULL)

Arguments

`formula`	A formula object, with the response on the left-hand side of a '~' operator, and the covariates and vaccine() function on the right-hand side. The response must be a survival object as returned by the 'Surv' function of the survival package. See Details for further information. The vaccine() function must be used to specify the entry time and vaccination information. See ?vaccine and Details for further information.
`data`	A data.frame object. The data.frame in which to interpret the variable names in formula. Must contain the entry time, the event time, the event status, the vaccination status, the vaccination time, and any covariates. All time variables must be provided in units of days. See Details.
`plots`	A logical object. If TRUE, plots of the estimated curve of vaccine efficacy in reducing attack rate and the estimated curve of vaccine efficacy in reducing the hazard rate will be automatically generated. If FALSE, plots will not be generated, but the data are available through the returned value object.
`timePts`	A numeric vector object or NULL. The endpoints of the time periods for which the vaccine efficacy in reducing the attack rate is to be shown. If NULL, a default sequence of 60-day intervals is used. If tau < 60 days, this input must be provided.
`bandwidth`	A numeric object. Tuning parameter for the bandwidth used for kernel estimation of the vaccine efficacy in reducing the hazard rate; this input is ignored if plots=FALSE.

Details

In dove(), the hazard ratio for the vaccine effect is a nonparametric function of time for which confidence intervals are not provided. The sister function, dove2(), assumes that the log hazard ratio for the vaccine effect is a piecewise linear function of time; it provides more precise and more stable estimates of vaccine efficacy on the hazard rate and includes proper confidence intervals.

The information required for an analysis is

Entry Time:: Calendar time when the participant enters the trial.
Event Time:: Calendar time when the participant experiences the clinical event of interest (e.g., symptomatic COVID-19) or their follow-up ends, whichever occurs first.
Event Status:: Binary indicator taking value 1 if the clinical event of interest occurs before the end of follow-up and 0 otherwise.
Vaccination Status:: Binary indicator taking value 1 if vaccination occurs before the end of follow-up and 0 otherwise.
Vaccination Time:: Calendar time when vaccination takes place, with an arbitrary non-negative value if the participant is not vaccinated.
Covariates:: Baseline covariates (e.g., priority group, age, ethnicity).

Note that all times are to be specified relative to the start of the trial and are specified in units of days. Thus, for individuals that received vaccination, entry_time <= vaccination_time <= event_time. And for individuals that did not receive vaccination, entry_time <= event_time; for these participants, vaccination_time can take any non-negative value (including NA or Inf).

The general structure of the formula input is

  Surv(event_time, event_status) ~ covariates + 
    vaccine(entry_time, vaccination_time, vaccination_status)

The response variable must be a survival analysis object as returned by the 'Surv()' function of package survival, where event_time is the observation time (formal argument 'time') and event_status is the status indicator input (formal argument 'event'). Specifically,

Surv(time = event_time, event = event_status)

The covariates can include categorical variables, for which all other categories are compared to the first category.

The vaccination and entry_time information must be specified through function 'vaccine()'. Specifically,

vaccine(entry_time, vaccination_status, vaccination_time)

For participants that did not receive the vaccine, vaccination_time can take any non-negative value (including NA or Inf). For individuals that received vaccination, if vaccination_time > event_time, or vaccination_time < entry_time, the case will be removed from the analysis and a message will be generated.

Value

An S3 object of class DOVE containing a list with elements

covariates

A matrix containing the estimated hazard ratio of each covariate, together with the (estimated) standard error, the 95% confidence interval, and the two-sided p-value for testing no covariate effect.

vaccine

A list containing two elements. The first element is the matrix containing the estimates of the vaccine efficacy in reducing the attack rate at all observed event times (VE_a), together with the 95% confidence intervals, as well as the vaccine efficacy in reducing the hazard rate at these times (VE_h). These results will be shown in graphical form if input plots = TRUE. The second element is the matrix containing the estimates of vaccine efficacy in reducing the attack rate over successive time periods, together with the 95% confidence intervals.

References

Lin, DY, Zeng, D, and Gilbert, PB (2021). Evaluating the long-term efficacy of COVID-19 vaccines. Clinical Infectious Diseases, ciab226, https://doi.org/10.1093/cid/ciab226.

Examples


data(doveData)

set.seed(1234)

ind <- sample(1:nrow(x = doveData), 500, FALSE)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full analysis of the doveData dataset

dove(formula = Surv(event.time, event.status) ~ priority + sex + 
                vaccine(entry.time, vaccine.status, vaccine.time),
     data = doveData[ind,])
data(doveData)

set.seed(1234)

ind <- sample(1:nrow(x = doveData), 500, FALSE)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full analysis of the doveData dataset

dove(formula = Surv(event.time, event.status) ~ priority + sex + 
                vaccine(entry.time, vaccine.status, vaccine.time),
     data = doveData[ind,])

Durability of Vaccine Efficacy

Description

Estimates the potentially waning long-term efficacy of vaccines in randomized, placebo-controlled clinical trials with staggered enrollment of participants and sequential crossover of placebo recipients. The log hazard ratio for the vaccine effect is assumed to be a piecewise linear function of time since vaccination, whereas the baseline hazard function is nonparametric.

Usage

dove2(
  formula,
  data,
  plots = TRUE,
  changePts = NULL,
  constantVE = FALSE,
  timePts = NULL
)
dove2(
  formula,
  data,
  plots = TRUE,
  changePts = NULL,
  constantVE = FALSE,
  timePts = NULL
)

Arguments

`formula`	A formula object, with the response on the left-hand side of a '~' operator, and the covariates and vaccine() function on the right-hand side. The response must be a survival analysis object as returned by the 'Surv' function of the survival package. See Details for further information. The vaccine() function must be used to specify the entry time and vaccination information. See ?vaccine and Details for further information.
`data`	A data.frame object. The data.frame in which to interpret the variable names in formula. Must contain the entry time, the event time, the event status, the vaccination status, the vaccination time, and the covariates. See Details.
`plots`	A logical object. If TRUE (default), plots of the estimated VE in reducing the attack rate, the estimated VE in reducing the hazard rate, and their 95% confidence intervals will be automatically generated. If FALSE, plots will not be generated.
`changePts`	A numerical vector object or NULL. The potential change points (in days) of the piece-wise log-linear hazard ratio for the vaccine effect. See Details for further information. If NULL, one change point will automatically be selected among {28, 35, 42, 49, 56} (Weeks 4, 5, 6, 7, 8) by the Akaike information criterion (AIC).
`constantVE`	A logical object. If FALSE (default), VE is allowed to vary after the last change point. If TRUE, VE is assumed to be constant after the last change point.
`timePts`	A numerical vector object or NULL. The endpoints (in days) of the time periods for which the VE in reducing the attack rate are to be estimated. If NULL, a default sequence $t_1, 2t_1, 3t_1, \dots$ will be used, where $t_1$ is the first change point. The sequence ends at the maximum of the event times from all participants. This input is ignored when constantVE = TRUE.

Details

In dove2(), the log hazard ratio for the vaccine effect is a piecewise linear function of time since vaccination. Its sister function, dove(), allows the hazard ratio to be a nonparametric function of time for which confidence intervals are not provided. The approach implemented in dove2() provides more precise and more stable estimates of vaccine efficacy on the hazard rate and includes proper confidence intervals.

The information required for an analysis is

Entry Time:: Calendar time when the participant enters the trial.
Event Time:: Calendar time when the participant experiences the clinical event of interest (e.g., symptomatic COVID-19) or the follow-up ends, whichever occurs first.
Event Status:: Binary indicator taking value 1 if the clinical event of interest occurs before the end of follow-up and 0 otherwise.
Vaccination Status:: Binary indicator taking value 1 if vaccination occurs before the end of follow-up and 0 otherwise.
Vaccination Time:: Calendar time when vaccination takes place, with NA, Inf, or an arbitrary non-negative value if the participant is not vaccinated.
Covariates:: Baseline covariates (e.g., priority group, age, ethnicity).

Note that all the time variables are measured from the start of the clinical trial and are specified in units of days. For each individual, the entry_time, event_time, and vaccination_time must satisfy entry_time $\le$ event_time and entry_time $\le$ vaccination_time. If entry_time > event_time or entry_time > vaccination_time, the case will be removed from the analysis and a message will be generated.

The general structure of the formula input is

  Surv(event_time, event_status) ~ covariates + 
    vaccine(entry_time, vaccination_status, vaccination_time)

Surv(time = event_time, event = event_status)

The covariates can be either numerical or categorical. If categorical covariates are provided, all other categories are compared to the first category. A model without covariates is also allowed.

Value

An S3 object of class DOVE containing a list with elements

`call`	The unevaluated call.
`changePts`	The changePts of the analysis.
`covariates`	A matrix containing the estimated (log) hazard ratio of each covariate, together with the estimated standard error, the 95% confidence interval, and the two-sided p-value for testing no covariate effect. NA if no covariate is included in the model.
`vaccine`	A list containing one or three elements, depending on the value of constantVE. If constantVE = TRUE, the only element is named 'VE' and is a vector containing the estimate of constant VE, its standard error estimate, and the 95% confidence interval. If constantVE = FALSE, three matrices are returned. The first matrix named 'VE_a' contains the daily VE estimates in reducing the attack rate, together with the 95% confidence intervals. The second matrix named 'VE_h' contains the daily VE estimates in reducing the hazard rate, together with the 95% confidence intervals. The third matrix named 'VE_period' contains the estimates of VE in reducing the attack rate over successive time periods according to timePts, together with the 95% confidence intervals.

References

Lin, D-Y, Gu, Y., Zeng, D., Janes, H. E., and Gilbert, P. B. (2021). Evaluating vaccine efficacy against SARS-CoV-2 infection. Clinical Infectious Diseases, ciab630, https://doi.org/10.1093/cid/ciab630.

Examples


data(doveData)

set.seed(1234)
smp <- sample(1L:nrow(x = doveData), size = 2500L)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full analysis of the doveData dataset

# Fit the model with default settings
dove2(formula = Surv(event.time, event.status) ~ priority + sex + 
                vaccine(entry.time, vaccine.status, vaccine.time), 
      data = doveData[smp,])

# Specify Week 4 as the change point
# Assume a potentially waning VE after 4 weeks
# Estimate VE_a over 0-4, 4-16, 16-28, 28-40 weeks
dove2(formula = Surv(event.time, event.status) ~ priority + sex + 
                vaccine(entry.time, vaccine.status, vaccine.time), 
      data = doveData[smp,],
      changePts = 4*7,
      timePts = c(4, 16, 28, 40)*7)
      
# Specify multiple change points at Weeks 4 and 8
# Assume a constant VE after 8 weeks
dove2(formula = Surv(event.time, event.status) ~ priority + sex + 
                vaccine(entry.time, vaccine.status, vaccine.time), 
      data = doveData[smp,],
      changePts = c(4, 8)*7,
      constantVE = TRUE)
data(doveData)

set.seed(1234)
smp <- sample(1L:nrow(x = doveData), size = 2500L)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full analysis of the doveData dataset

# Fit the model with default settings
dove2(formula = Surv(event.time, event.status) ~ priority + sex + 
                vaccine(entry.time, vaccine.status, vaccine.time), 
      data = doveData[smp,])

# Specify Week 4 as the change point
# Assume a potentially waning VE after 4 weeks
# Estimate VE_a over 0-4, 4-16, 16-28, 28-40 weeks
dove2(formula = Surv(event.time, event.status) ~ priority + sex + 
                vaccine(entry.time, vaccine.status, vaccine.time), 
      data = doveData[smp,],
      changePts = 4*7,
      timePts = c(4, 16, 28, 40)*7)
      
# Specify multiple change points at Weeks 4 and 8
# Assume a constant VE after 8 weeks
dove2(formula = Surv(event.time, event.status) ~ priority + sex + 
                vaccine(entry.time, vaccine.status, vaccine.time), 
      data = doveData[smp,],
      changePts = c(4, 8)*7,
      constantVE = TRUE)

Toy Dataset For Illustration

Description

This data set is provided to illustrate the use of the software. It was simulated under a priority-tier dependent crossover design with a ramping vaccine effect between dose 1 and dose 2.

Usage

data(doveData)
data(doveData)

Format

doveData is a data.frame containing 40,000 participants The data.frame contains 7 columns,

entry.time: The entry time in days
event.time: The observation time in days
event.status: The event indicator (1=event; 0=censored)
vaccine.time: The time of vaccination in days; NA if not vaccinated
vaccine.status: The indicator of vaccination (1 = vaccinated; 0 = not vaccinated)
priority: A composite baseline risk score taking values 1-5
sex: A binary indicator of sex (male/female)

Plot Estimated Vaccine Efficacy

Description

Generates plots of the estimated vaccine efficacy in reducing attack rate, the estimated vaccine efficacy in reducing the hazard rate, and their 95% confidence intervals.

Usage

## S3 method for class 'DOVE'
plot(x, y, ..., bandwidth = NULL)
## S3 method for class 'DOVE'
plot(x, y, ..., bandwidth = NULL)

Arguments

`x`	An DOVE object. The value object returned by dove() and dove2().
`y`	ignored.
`...`	ignored
`bandwidth`	A numeric vector object. A tuning parameter for the bandwidth used for kernel estimation of the vaccine efficacy in reducing the hazard rate for objects returned by dove(). This input is ignored for objects returned by dove2().

Value

No return value, called to produce graphical elements.

Examples


data(doveData)

set.seed(1234)

smp <- sample(1:nrow(x = doveData), 500, FALSE)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full dove() analysis of the doveData dataset

result <- dove(formula = Surv(event.time, event.status) ~ priority + sex + 
                         vaccine(entry.time, vaccine.status, vaccine.time),
               data = doveData[smp,])

plot(x = result, bandwidth = c(0.5,1.0))

set.seed(1234)
smp <- sample(1L:nrow(x = doveData), size = 2500L)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full dove2() analysis of the doveData dataset

# Fit the model with default settings
result <- dove2(formula = Surv(event.time, event.status) ~ priority + sex + 
                          vaccine(entry.time, vaccine.status, vaccine.time), 
                data = doveData[smp,])

plot(x = result)

data(doveData)

set.seed(1234)

smp <- sample(1:nrow(x = doveData), 500, FALSE)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full dove() analysis of the doveData dataset

result <- dove(formula = Surv(event.time, event.status) ~ priority + sex + 
                         vaccine(entry.time, vaccine.status, vaccine.time),
               data = doveData[smp,])

plot(x = result, bandwidth = c(0.5,1.0))

set.seed(1234)
smp <- sample(1L:nrow(x = doveData), size = 2500L)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full dove2() analysis of the doveData dataset

# Fit the model with default settings
result <- dove2(formula = Surv(event.time, event.status) ~ priority + sex + 
                          vaccine(entry.time, vaccine.status, vaccine.time), 
                data = doveData[smp,])

plot(x = result)

Print the Primary Results of a dove() or dove2() Analysis

Description

Print the primary results of a dove() or dove2() analysis.

Usage

## S3 method for class 'DOVE'
print(x, ...)
## S3 method for class 'DOVE'
print(x, ...)

Arguments

`x`	An DOVE object. The value object returned by a call to dove() or dove2()
`...`	ignored

Value

No return value, called to display key results.

Examples


data(doveData)

set.seed(1234)

smp <- sample(1:nrow(x = doveData), 500, FALSE)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full dove() analysis of the doveData dataset

result <- dove(formula = Surv(event.time, event.status) ~ priority + sex + 
                         vaccine(entry.time, vaccine.status, vaccine.time),
               data = doveData[smp,])

print(x = result)

set.seed(1234)
smp <- sample(1L:nrow(x = doveData), size = 2500L)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full dove2() analysis of the doveData dataset

# Fit the model with default settings
result <- dove2(formula = Surv(event.time, event.status) ~ priority + sex + 
                          vaccine(entry.time, vaccine.status, vaccine.time), 
                data = doveData[smp,])

print(x = result)

data(doveData)

set.seed(1234)

smp <- sample(1:nrow(x = doveData), 500, FALSE)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full dove() analysis of the doveData dataset

result <- dove(formula = Surv(event.time, event.status) ~ priority + sex + 
                         vaccine(entry.time, vaccine.status, vaccine.time),
               data = doveData[smp,])

print(x = result)

set.seed(1234)
smp <- sample(1L:nrow(x = doveData), size = 2500L)

# NOTE: This sample size is chosen for example only -- larger data sets
# should be used.
# See the vignette for a full dove2() analysis of the doveData dataset

# Fit the model with default settings
result <- dove2(formula = Surv(event.time, event.status) ~ priority + sex + 
                          vaccine(entry.time, vaccine.status, vaccine.time), 
                data = doveData[smp,])

print(x = result)

Specify Vaccination Variables and Entry Time

Description

This function is used in the model statements of dove() and dove2() to specify the vaccination time, vaccination status, and entry time.

Usage

vaccine(entry_time, vaccination_status, vaccination_time)
vaccine(entry_time, vaccination_status, vaccination_time)

Arguments

`entry_time`	The variable for the time when the participant enters the trial. Entry times must be non-negative and complete.
`vaccination_status`	The variable indicating the vaccination status: 1 = vaccinated; 0 = not vaccinated. Vaccination status must be binary, integer (or be able to be cast as integer without loss of information), and complete.
`vaccination_time`	The variable for the time when vaccination takes place. Vaccination time must be non-negative for vaccinated participants and can be any non-negative value, NA or Inf if a participant was not vaccinated during the trial.

Details

For participants that were vaccinated, times must obey entry_time $\le$ vaccination_time. If a case is found to violate this relationship, its entry_time is set to NA and it is removed from the analysis.

Value

This function is intended to be used only in the model statements of dove() and dove2(). The result, a matrix, is used internally.

Package 'DOVE'

Help Index

Durability of Vaccine Efficacy

Description

Usage

Arguments

Details

Value

References

Examples

Durability of Vaccine Efficacy

Description

Usage

Arguments

Details

Value

References

Examples

Toy Dataset For Illustration

Description

Usage

Format

Plot Estimated Vaccine Efficacy

Description

Usage

Arguments

Value

Examples

Print the Primary Results of a dove() or dove2() Analysis

Description

Usage

Arguments

Value

Examples

Specify Vaccination Variables and Entry Time

Description

Usage

Arguments

Details

Value