VEpowerPP: Unconditional Power to Detect Positive Treatment Efficacy in a Per-Protocol Cohort

Description

VEpowerPP computes unconditional power to detect positive treatment (vaccine) efficacy in per-protocol cohorts identified in simTrial-generated data-sets.

Usage

VEpowerPP(dataList, lowerVEuncPower, alphaUncPower, VEcutoffWeek, stage1,
  outName = NULL, saveDir = NULL, verbose = TRUE)

Arguments

dataList

if saveDir = NULL, a list of objects (lists) returned by censTrial; otherwise a list of .RData file names (character strings) generated by censTrial

lowerVEuncPower

a numeric value specifying a one-sided null hypothesis H0: VE(VEcutoffWeek--stage1) \(\le\) lowerVEuncPower x 100%. Unconditional power (i.e., accounting for sequential monitoring) to reject H0 in the per-protocol cohort is calculated, where the rejection region is defined by the lower bound of the two-sided (1-alphaUncPower) x 100% confidence interval for VE(VEcutoffWeek--stage1) being above lowerVEuncPower (typically a number in the 0--0.5 range).

alphaUncPower

one minus the nominal confidence level of the two-sided confidence interval used to test the one-sided null hypothesis H0: VE(VEcutoffWeek--stage1) \(\le\) lowerVEuncPower x 100% against the alternative hypothesis H1: VE(VEcutoffWeek--stage1) \(>\) lowerVEuncPower x 100%.

VEcutoffWeek

a cut-off time (in weeks). Only subjects with the follow-up time exceeding VEcutoffWeek are included in the per-protocol cohort.

stage1

the final week of stage 1 in a two-stage trial

outName

a character string specifying the output .RData file name. If outName = NULL but saveDir is specified, the output file is named VEpwPP.RData.

saveDir

a character string specifying a path for the output directory. If supplied, the output is saved as an .RData file named outName 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)

Value

If saveDir is specified, the output list (named pwList) is saved as an .RData file named outName (or VEpwPP.RData if left unspecified); otherwise the output list is returned. The output object is a list (of equal length as dataList) of lists with the following components:

VE: a numeric vector of VE(VEcutoffWeek--stage1) estimates for each missing vaccination probability in missVaccProb of simTrial
VEpwPP: a numeric vector of powers to reject the null hypothesis H0: VE(VEcutoffWeek--stage1) \(\le\) lowerVEuncPower x 100% for each missing vaccination probability in missVaccProb of simTrial

Details

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

A per-protocol cohort indicator is assumed to be included in the simTrial-generated data-sets, which is ensured by specifying the missVaccProb argument in simTrial.

VE(VEcutoffWeek--stage1) is estimated as one minus the ratio of Nelson-Aalen-based cumulative incidence functions. VEpowerPP computes power to reject the null hypothesis H0: VE(VEcutoffWeek--stage1) \(\le\) lowerVEuncPower x 100%. H0 is rejected if the lower bound of the two-sided (1-alphaUncPower) x 100% confidence interval for VE(VEcutoffWeek--stage1) lies above lowerVEuncPower.

Examples

Run this code

# NOT RUN {
simData <- simTrial(N=rep(1000, 2), aveVE=c(0, 0.4), VEmodel="half", 
                    vePeriods=c(1, 27, 79), enrollPeriod=78, 
                    enrollPartial=13, enrollPartialRelRate=0.5, dropoutRate=0.05, 
                    infecRate=0.04, fuTime=156, 
                    visitSchedule=c(0, (13/3)*(1:4), seq(13*6/3, 156, by=13*2/3)),
                    missVaccProb=c(0,0.05,0.1,0.15), VEcutoffWeek=26, nTrials=5, 
                    stage1=78, randomSeed=300)

monitorData <- monitorTrial(dataFile=simData, stage1=78, stage2=156, 
                            harmMonitorRange=c(10,100), alphaPerTest=NULL, 
                            nonEffStartMethod="FKG", nonEffInterval=20, 
                            lowerVEnoneff=0, upperVEnoneff=0.4, 
                            highVE=0.7, stage1VE=0, lowerVEuncPower=0, 
                            alphaNoneff=0.05, alphaHigh=0.05, alphaStage1=0.05, 
                            alphaUncPower=0.05, estimand="cuminc", lagTime=26)

censData <- censTrial(dataFile=simData, monitorFile=monitorData, stage1=78, stage2=156)

VEpwPP <- VEpowerPP(dataList=list(censData), lowerVEuncPower=0, alphaUncPower=0.05,
                    VEcutoffWeek=26, stage1=78)

### alternatively, to save the .RData output file (no '<-' needed):
###
### simTrial(N=rep(1000, 2), aveVE=c(0, 0.4), VEmodel="half", 
###          vePeriods=c(1, 27, 79), enrollPeriod=78, enrollPartial=13, 
###          enrollPartialRelRate=0.5, dropoutRate=0.05, infecRate=0.04, fuTime=156, 
###          visitSchedule=c(0, (13/3)*(1:4), seq(13*6/3, 156, by=13*2/3)), 
###          missVaccProb=c(0,0.05,0.1,0.15), VEcutoffWeek=26, nTrials=5, 
###          stage1=78, saveDir="./", randomSeed=300)
###
### monitorTrial(dataFile=
###          "simTrial_nPlac=1000_nVacc=1000_aveVE=0.4_infRate=0.04.RData", 
###          stage1=78, stage2=156, harmMonitorRange=c(10,100), alphaPerTest=NULL, 
###          nonEffStartMethod="FKG", nonEffInterval=20, 
###          lowerVEnoneff=0, upperVEnoneff=0.4, highVE=0.7, stage1VE=0, 
###          lowerVEuncPower=0, alphaNoneff=0.05, alphaHigh=0.05, alphaStage1=0.05, 
###          alphaUncPower=0.05, estimand="cuminc", lagTime=26, saveDir="./")
###
### censTrial(dataFile=
###  "simTrial_nPlac=1000_nVacc=1000_aveVE=0.4_infRate=0.04.RData",
###  monitorFile=
###  "monitorTrial_nPlac=1000_nVacc=1000_aveVE=0.4_infRate=0.04_cuminc.RData",
###  stage1=78, stage2=156, saveDir="./")
###
### VEpowerPP(dataList=
###  list("trialDataCens_nPlac=1000_nVacc=1000_aveVE=0.4_infRate=0.04_cuminc.RData"),
###  lowerVEuncPower=0, alphaUncPower=0.05, VEcutoffWeek=26, stage1=78, saveDir="./")

# }