R: Treatment Arm-Pooled Simulation-Based Completion of a...

completeTrial.pooledArms {futility}

R Documentation

Treatment Arm-Pooled Simulation-Based Completion of a Randomized Efficacy Trial with a Time-to-Event Endpoint and Fixed Follow-up Using an Interim Data-set

Description

Considers MITT data collected through an interim timepoint and generates independent time-to-event data-sets, ignoring treatment assignments, to assess the distribution of the number of treatment arm-pooled endpoints at the end of the follow-up period. A Bayesian model for the treatment arm-pooled endpoint rate, offering the option to specify a robust mixture prior distribution, is used for generating future data (see the vignette).

Usage

completeTrial.pooledArms(interimData, nTrials, N, enrollRate = NULL,
  enrollRatePeriod = NULL, eventPriorWeight, eventPriorRate = NULL,
  fixedDropOutRate = NULL, ppAnalysis = FALSE, missVaccProb = NULL,
  ppAtRiskTimePoint = NULL, fuTime, mixture = FALSE,
  mix.weights = NULL, eventPriorWeightRobust = NULL, visitSchedule,
  visitSchedule2 = NULL, saveFile = NULL, saveDir = NULL,
  randomSeed = NULL)

Arguments

`interimData`	a data frame capturing observed MITT data at an interim timepoint that contains one row per enrolled participant in the MITT cohort and the following variables: `arm` (treatment arm), `schedule2` (an indicator that a participant follows the `visitSchedule2` schedule, e.g., participants who discontinue study product administration may remain in primary follow-up on a different schedule), `entry` (number of weeks since the reference date until the enrollment date), `exit` (number of weeks since the reference date until the trial exit date defined as the date of either infection diagnosis, dropout, or primary follow-up completion, whichever occurs first; `NA` for participants still in primary follow-up), `last_visit_dt` (number of weeks since the reference date until the last visit date), `event` (event indicator), `dropout` (dropout indicator), `complete` (indicator of completed follow-up), `followup` (indicator of being in primary follow-up). The reference date is defined as the enrollment date of the first participant. The variables `entry`, `exit`, and `last_visit_dt` use week as the unit of time. Month is defined as 52/12 weeks.
`nTrials`	the number of trials to be simulated
`N`	the total target number of enrolled participants
`enrollRate`	a treatment arm-pooled weekly enrollment rate used for completing enrollment if fewer than `N` participants were enrolled in `interimData`. If `NULL` (default), the rate is calculated as the average over the last `enrollRatePeriod` weeks of enrollment in `interimData`. If equal to a numerical value, then `enrollRatePeriod` is ignored.
`enrollRatePeriod`	the length (in weeks) of the time period preceding the time of the last enrolled participant in `interimData` that the average weekly enrollment rate will be based on and used for completing enrollment. If `NULL` (default), then `enrollRate` must be specified.
`eventPriorWeight`	a numeric value in `[0,1]` representing a weight assigned to the prior gamma distribution of the treatment arm-pooled event rate at the time when 50% of the estimated total person-time at risk has been accumulated (see the vignette)
`eventPriorRate`	a numeric value of a treatment arm-pooled prior mean incidence rate for the endpoint, expressed as the number of events per person-year at risk. If `NULL` (default), then use the observed rate in `interimData`.
`fixedDropOutRate`	the pre-trial assumed annual dropout rate. If `NULL` (default), then the observed treatment arm-pooled dropout rate is used.
`ppAnalysis`	a logical value (`FALSE` by default) indicating whether an indicator of membership in the per-protocol cohort shall be generated based on complete MITT data. If `TRUE`, then `interimData` must include two additional variables: `missVacc` (an indicator of a missed vaccination) and `pp` (an indicator of membership in the per-protocol cohort; `NA` for participants with an indeterminate status).
`missVaccProb`	a probability that a participant misses at least one vaccination. If `NULL` (default) and `ppAnalysis=TRUE`, then `missVaccProb` is calculated as the sample proportion of MITT participants in `interimData` with a missed vaccination using the `missVacc` variable. If `ppAnalysis=TRUE`, then the indicator of a missed vaccination for participants in `interimData` with `pp=NA` and future enrolled participants is sampled from the Bernoulli distribution with probability `missVaccProb`.
`ppAtRiskTimePoint`	a minimal follow-up time (in weeks) for a participant to qualify for inclusion in the per-protocol cohort (`NULL` by default)
`fuTime`	a follow-up time (in weeks) of each participant
`mixture`	a logical value indicating whether to use the robust mixture approach (see the vignette). If equal to `FALSE` (default), then `mix.weights` and `eventPriorWeightRobust` are ignored.
`mix.weights`	a numeric vector of length 2 representing prior weights (values in `[0,1]`) of the informative and the weakly informative component, respectively, of the prior gamma-mixture distribution of the treatment arm-pooled event rate. The two weights must sum up to 1. If `NULL` (default) and `mixture=TRUE`, then `c(0.8,0.2)` is used.
`eventPriorWeightRobust`	a numeric value representing the weight `w` used to calculate the `\beta` parameter of the weakly informative gamma distribution in the mixture prior. If `NULL` (default) and `mixture=TRUE`, then `1/200` is used.
`visitSchedule`	a numeric vector of visit weeks at which testing for the endpoint is conducted
`visitSchedule2`	a numeric vector of visit weeks at which testing for the endpoint is conducted in a subset of participants (e.g., those who discontinue administration of the study product but remain in follow-up). If `NULL` (default), everyone is assumed to follow `visitSchedule`.
`saveFile`	a character string specifying an `.RData` file storing the output list. If `NULL` and `saveDir` is specified, the file name will be generated. If, in turn, `saveFile` is specified but `saveDir` equals `NULL`, then `saveFile` is ignored, and the output list will be returned.
`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.
`randomSeed`	seed of the random number generator for simulation reproducibility

Value

If saveDir is specified, the output list (named trialObj) is saved as an .RData file; 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 the variables arm, entry, exit, event, and dropout storing the treatment assignments, enrollment times, study exit times, event indicators, and dropout indicators respectively. The observed follow-up times can be recovered as exit - entry. If ppAnalysis=TRUE, then the indicators of belonging to the per-protocol cohort (named pp) are included.
nTrials: the number of simulated trials
N: the total number of enrolled trial participants
rates: a list with three components:
- enrollRate: the treatment arm-pooled weekly enrollment rate
- dropRate: fixedDropOutRate, or, if NULL, the annual treatment arm-pooled dropout rate in interimData
- eventPostRate: a numeric vector of length nTrials of the treatment arm-pooled annual event rates sampled from the posterior distribution
BetaOverBetaPlusTk: the weight placed on the prior mean event rate
TkOverTstar: the ratio of the observed person-time at risk to the estimated total person-time at risk, with the event rate set equal to eventPriorRate in the estimator for the total person-time at risk
randomSeed: seed of the random number generator for simulation reproducibility
w.post: the weights, summing up to 1, of the gamma components of the posterior mixture distribution of the treatment arm-pooled event rate. If mixture=FALSE, then w.post=NA.

Examples

arm <- rep(c("C3","T1","T2"), each=250)
schedule <- rbinom(length(arm), 1, 0.01)
entry <- rpois(length(arm), lambda=60)
entry <- entry - min(entry)
last_visit_dt <- entry + runif(length(arm), min=0, max=80)
event <- rbinom(length(arm), 1, 0.01)
dropout <- rbinom(length(arm), 1, 0.02)
dropout[event==1] <- 0
exit <- rep(NA, length(arm))
exit[event==1] <- last_visit_dt[event==1] + 5
exit[dropout==1] <- last_visit_dt[dropout==1] + 5
followup <- ifelse(event==1 | dropout==1, 0, 1)
interimData <- data.frame(arm=arm, schedule2=schedule, entry=entry, exit=exit,
last_visit_dt=last_visit_dt, event=event, dropout=dropout, complete=0,
followup=followup)

completeData <- completeTrial.pooledArms(interimData=interimData, nTrials=5, N=1500,
enrollRatePeriod=24, eventPriorWeight=0.5, eventPriorRate=0.001, fuTime=80,
visitSchedule=seq(0, 80, by=4),
visitSchedule2=c(0,seq(from=8,to=80,by=12)), randomSeed=9)
### alternatively, to save the .RData output file (no '<-' needed):
completeTrial.pooledArms(interimData=interimData, nTrials=5, N=1500,
enrollRatePeriod=24, eventPriorWeight=0.5, eventPriorRate=0.001, fuTime=80,
visitSchedule=seq(0, 80, by=4),
visitSchedule2=c(0,seq(from=8,to=80,by=12)), saveDir="./", randomSeed=9)