simTrial: Simulation of Multi-Arm Randomized Phase IIb/III Efficacy...

In mjuraska/seqDesign: Simulation and Group-Sequential Monitoring of Randomized Treatment Efficacy Trials with Time-to-Event Endpoints

Simulation of Multi-Arm Randomized Phase IIb/III Efficacy Trials with Time-to-Event Endpoints

Description

simTrial generates independent time-to-event data-sets according to a user-specified trial design. The user makes assumptions about the enrollment, dropout, and infection processes in each treatment arm.

Usage

simTrial(
  N,
  VEmodel = c("half", "constant", "manual"),
  aveVE = NULL,
  vePeriods,
  veByPeriod = NULL,
  enrollPeriod,
  enrollPartial,
  enrollPartialRelRate,
  dropoutRate,
  infecRate,
  fuTime,
  visitSchedule,
  missVaccProb = NULL,
  VEcutoffWeek,
  nTrials,
  blockSize = NULL,
  stage1,
  saveFile = NULL,
  saveDir = NULL,
  verbose = TRUE,
  randomSeed = NULL
)

Arguments

N	a numeric vector specifying the numbers of enrolled trial participants per treatment arm. The length of N equals the total number of treatment arms, and the first component of N represents the control arm. #' @param VEmodel a character string specifying whether VE is assumed to be constant throughout the follow-up period (option "constant"), have two or three levels over time specified by aveVE (option "half", default), or have multiple levels fully specified by veByPeriod (option "manual"). The option "half" allows either a 2- or 3-level VE model (specified by the vePeriods vector with either 2 or 3 components, respectively, and aveVE). Under the option "half", both the 2- and 3-level VE model assumes a maximal VE in the second time interval such that, when halved in the first interval, the weighted average of VE over the first two time intervals equals aveVE. Only the first character is necessary.
aveVE	a numeric vector containing, for each treatment arm in N, a time-averaged vaccine efficacy (VE), defined as the weighted average of VEs in two or three time intervals specified by vePeriods. aveVE and vePeriods together characterize the VE model if VEmodel is set to "constant" or "half"; otherwise, aveVE is ignored. If \code{VEmodel} = \code{"half"}, then aveVE is defined as follows: both the 2- and 3-level VE model assumes a maximal VE in the second time interval such that, when halved in the first interval, the weighted average of VE over the first two time intervals equals aveVE. aveVE is also applied thereafter. The components of N and aveVE correspond to each other.
vePeriods	a numeric vector defining start times (in weeks) of time intervals with (potentially) distinct VE levels depending on the choice of VEmodel. The value 1 in the vector signifies the beginning of follow-up. If VEmodel equals "constant", then vePeriods must have length 1 (typically then vePeriods <- 1). If VEmodel equals "half", then vePeriods must have length 2 or 3.
veByPeriod	a list (NULL by default) allowing to specify the VE level for each time interval in vePeriods for each treatment arm (including the control arm). The VE model can be specified in two ways: (a) by providing a vector of 'full' VE levels for the treatment arms starting with the control arm (component fullVE) and, for each treatment arm, vectors of fractions of fullVE pertaining to the time intervals (component C1 for the control arm, and T1, T2, etc. for the active arms), or (b) by providing, for each treatment arm, a vector of the actual VE levels pertaining to the time intervals (components C1, T1, T2, etc.). Note that the first component after fullVE, if it exists, must be C1 for the control arm, followed by the active arms. The vector fullVE, if it exists, has the same length as the number of arms, while the vectors C1, T1, T2, etc. have the same length as the number of time intervals in vePeriods. If the VE model is specified via veByPeriod, then aveVE will be ignored.
enrollPeriod	the final week of the enrollment period
enrollPartial	the final week of the portion of the enrollment period with a reduced enrollment rate defined by enrollPartialRelRate
enrollPartialRelRate	a non-negative value characterizing the fraction of the weekly enrollment rate governing enrollment from week 1 until week enrollPartial
dropoutRate	a (prior) dropout probability within 1 year
infecRate	a (prior) infection probability within 1 year in the control arm
fuTime	a follow-up time (in weeks) of each participant
visitSchedule	a numeric vector listing the visit weeks at which testing for the endpoint is conducted
missVaccProb	a numeric vector with conditional probabilities of having missed a vaccination given the follow-up time exceeds VEcutoffWeek weeks. For each component, a separate per-protocol indicator is generated. Each per-protocol cohort includes subjects with (i) a non-missing vaccination, and (ii) follow-up time exceeding VEcutoffWeek weeks. If NULL, no per-protocol indicators are included.
VEcutoffWeek	a time cut-off (in weeks); the follow-up time exceeding VEcutoffWeek weeks is required for inclusion in the per-protocol cohort
nTrials	the number of trials to be simulated
blockSize	a constant block size to be used in permuted-block randomization. The choice of blockSize requires caution to achieve the desired balance of treatment assignments within a block.
stage1	the final week of stage 1 in a two-stage trial
saveFile	a character string specifying the name of the output .RData file. If NULL (default), a default file name will be used.
saveDir	a character string specifying a path for the output directory. If supplied, the output is saved as an .RData file in the directory; otherwise the output is returned as a list.
verbose	a logical value indicating whether information on the output directory and file name should be printed out (default is TRUE)
randomSeed	sets seed of the random number generator for simulation reproducibility

Details

All time variables use week as the unit of time. Month is defined as 52/12 weeks.

The prior weekly enrollment rate is calculated based on the duration of the enrollment periods with reduced/full enrollment rates and the total number of subjects to be enrolled.

The weekly enrollment, dropout and infection rates used for generating trial data are sampled from specified prior distributions (the prior annual dropout and infection probabilities are specified by the user). The default choice considers non-random point-mass distributions, i.e., the prior rates directly govern the accumulation of trial data.

Subjects' enrollment is assumed to follow a Poisson process with a time-varying rate (the argument enrollPartialRelRate characterizes a reduced enrollment rate applied to weeks 1 through enrollPartial, i.e., full enrollment starts at week enrollPartial+1). The number of enrolled subjects is determined by the vector N.

Dropout times are assumed to follow an exponential distribution where the probability of a dropout within 1 week is equal to dropoutRate/52.

Permuted-block randomization is used for assigning treatment labels. If left unspecified by the user, an appropriate block size, no smaller than 10, will computed and used. The function getBlockSize can be used to determine appropriate block sizes (see help(getBlockSize)).

Infection times are generated following the VE schedule characterized by aveVE, VEmodel and vePeriods. Independent exponential times are generated within each time period of constant VE, and their minimum specifies the right-censored infection time. Exponential rates are chosen that satisfy the user-specified requirements on the treatment- and time-period-specific probabilities of an infection within 1 week (in the control arm, the infection probability within 1 week uniformly equals infecRate/52).

Infection diagnosis times are calculated according to the visitSchedule. The observed follow-up time is defined as the minumum of the infection diagnosis time, dropout time, and fuTime.

Value

If saveDir is specified, the output list (named trialObj) is saved as an .RData file (the output directory path is printed); otherwise it is returned. The output object is a list with the following components:

• trialData: a list with nTrials components each of which is a data.frame with at least the variables trt, entry, exit, and event storing the treatment assignments, enrollment times, study exit times, and event indicators, respectively. The observed follow-up times can be recovered as exit - entry. Indicators of belonging to the per-protocol cohort (named pp1, pp2, etc.) are included if missVaccProb is specified.

• NinfStage1: a list whose components are numeric vectors with the numbers of stage1 infections by treatment ([1] = control arm) for each simulated trial

• nTrials: the number of simulated trials

• N: the total number of enrolled trial participants

• nArms: the number of treatment arms

• trtAssgnProbs: a numeric vector containing the treatment assignment probabilities

• blockSize: the block size used for treatment assignment

• fuTime: the follow-up time (in weeks) of each participant

• rates: a list with three components: the prior weekly enrollment rate (enrollment), the prior probability of dropout within 1 week (dropout), and the prior probability of infection within 1 week (infection)

• enrollSchedule: a data.frame summarizing information on enrollment periods and corresponding relative enrollment rates (relative to the weekly "base" enrollment rate). The column names are start, end, and relativeRates.

• VEs: a list with components being numeric vectors containing VE levels assumed within time periods defined by vePeriods for each active treatment arm

• infecRates: a data.frame summarizing information on time periods of distinct VE across all treatment arms. The variables trt, start, end, and relRate carry treatment assignment labels, first and last week of a time interval, and the pertaining assumed hazard ratio in the given interval.

• randomSeed: the set seed of the random number generator for simulation reproducibility

See Also

monitorTrial, censTrial, and rankTrial

Examples

### constant VE throughout the follow-up period
simData <- simTrial(N=c(1000, rep(700, 2)), VEmodel="constant", 
                    aveVE=seq(0, 0.4, by=0.2), vePeriods=1, 
                    enrollPeriod=78, enrollPartial=13, enrollPartialRelRate=0.5, 
                    dropoutRate=0.05, infecRate=0.04, fuTime=156, 
                    visitSchedule=seq(0, 156, by=4),
                    missVaccProb=c(0,0.05,0.1,0.15), VEcutoffWeek=26, nTrials=5, 
                    stage1=78, randomSeed=300)
                    
### a 3-level VE model specified by 'aveVE' and 'vePeriods'
simData <- simTrial(N=c(1000, rep(700, 2)), VEmodel="half", 
                    aveVE=seq(0, 0.4, by=0.2), vePeriods=c(1, 27, 79), 
                    enrollPeriod=78, enrollPartial=13, enrollPartialRelRate=0.5, 
                    dropoutRate=0.05, infecRate=0.04, fuTime=156, 
                    visitSchedule=seq(0, 156, by=4),
                    missVaccProb=c(0,0.05,0.1,0.15), VEcutoffWeek=26, nTrials=5, 
                    stage1=78, randomSeed=300)
                    
### a manually entered VE model specified by 'veByPeriod' using 'fullVE'
### and fractions
simData <- simTrial(N=c(1000, rep(700, 2)), VEmodel="manual", 
                    vePeriods=c(1, 15, 27, 79),
                    veByPeriod=list(fullVE=c(0, 0.6, 0.8),
                                    C1=c(1, 1),
                                    T1=c(0.1, 2/3, 1, 0.75),
                                    T2=c(0.1, 0.5, 1, 0.9)), 
                    enrollPeriod=78, enrollPartial=13, enrollPartialRelRate=0.5, 
                    dropoutRate=0.05, infecRate=0.04, fuTime=156, 
                    visitSchedule=seq(0, 156, by=4),
                    missVaccProb=c(0,0.05,0.1,0.15), VEcutoffWeek=26, nTrials=5, 
                    stage1=78, randomSeed=300)
                    
### the same manually entered VE model as above by specifying the actual 
### VE levels in 'veByPeriod'
simData <- simTrial(N=c(1000, rep(700, 2)), VEmodel="manual", 
                    vePeriods=c(1, 15, 27, 79),
                    veByPeriod=list(C1=c(0, 0, 0, 0),
                                    T1=c(0.1, 2/3, 1, 0.75) * 0.6,
                                    T2=c(0.1, 0.5, 1, 0.9) * 0.8), 
                    enrollPeriod=78, enrollPartial=13, enrollPartialRelRate=0.5, 
                    dropoutRate=0.05, infecRate=0.04, fuTime=156, 
                    visitSchedule=seq(0, 156, by=4),
                    missVaccProb=c(0,0.05,0.1,0.15), VEcutoffWeek=26, nTrials=5, 
                    stage1=78, randomSeed=300)

### alternatively, to save the .RData output file (no '<-' needed):
###
### simTrial(N=c(1400, rep(1000, 2)), aveVE=seq(0, 0.4, by=0.2), VEmodel="half", 
###          vePeriods=c(1, 27, 79), enrollPeriod=78, enrollPartial=13, 
###          enrollPartialRelRate=0.5, dropoutRate=0.05, infecRate=0.04, fuTime=156, 
###          visitSchedule=seq(0, 156, by=4), 
###          missVaccProb=c(0,0.05,0.1,0.15), VEcutoffWeek=26, nTrials=5, 
###          stage1=78, saveDir="./", randomSeed=300)

mjuraska/seqDesign documentation built on Dec. 14, 2022, 4:26 p.m.