completeTrial.pooledArms: Treatment Arm-Pooled Simulation-Based Completion of a...

In futility: Interim Analysis of Operational Futility in Randomized Trials with Time-to-Event Endpoints and Fixed Follow-Up

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,
  expectedDose2timePoint = NULL,
  fuTime,
  targetNevents = NULL,
  mixture = FALSE,
  mix.weights = NULL,
  eventPriorWeightRobust = NULL,
  visitSchedule,
  visitSchedule2 = NULL,
  saveFile = NULL,
  saveDir = NULL,
  saveDataChars = FALSE,
  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 who were expected for the second vaccination and missed it, 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)
expectedDose2timePoint	a numeric value specifying the follow-up time (in weeks) at which a participant is considered expected for the second dose, i.e., when the visit window of the second vaccination visit has closed (NULL by default). It must be provided if ppAnalysis=TRUE.
fuTime	a follow-up time (in weeks) of each participant
targetNevents	an integer value specifying the target number of events in an event-driven design, the accrual of which triggers the primary analysis. The value is used exclusively for estimating the total person-time at risk accumulated for the primary analysis, which in turn is used for setting the values of the hyperparameters of the prior distribution.
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.
saveDataChars	a logical value (FALSE by default) for whether a file named dataChars.RData shall be generated with metrics characterizing the interim data for inclusion in the output report. If TRUE, the file is saved in saveDir.
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.

See Also

completeTrial.byArm

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):
tmpdir <- tempfile('futility_example_'); dir.create(tmpdir)
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=tmpdir, randomSeed=9)

futility documentation built on Feb. 17, 2026, 1:07 a.m.