Estimation of Size and Numbers of Cases and Controls in the Target Population of Active Treatment Recipients At Risk at the Biomarker Sampling Timepoint

Description

If the power calculation is done at the study design stage, the function estimates the size and numbers of cases and controls in the target population of active treatment recipients observed to be at risk at the biomarker sampling timepoint.

Usage

computeN(
  Nrand,
  tau,
  taumax,
  VEtauToTaumax,
  VE0toTau,
  risk0,
  dropoutRisk,
  propCasesWithS
)

Arguments

Details

The function estimates design parameters that are required as input to computePower. If the power calculation is done after the follow-up was completed, the estimates are replaced by the observed counterparts for use as input parameters in computePower.

The calculations include options to account for participant dropout by specifying dropoutRisk as well as for incomplete sample storage by specifying propCasesWithS.

The estimation procedure considers the standard survival analysis framework with failure and censoring times denoted by T and C, respectively, and makes the following assumptions:

1. T and C are independent.

2. T|Z=0 follows an exponential distribution with rate \theta_t and C|Z=0 follows an exponential distribution with rate \theta_c

3. RR_{\tau-\tau_{max}} := P(T <= \tau_{max}|T> \tau, Z=1)/P(T <= \tau_{max}|T> \tau, Z=0) is assumed to be equal to P(T <= t|T> \tau, Z=1)/P(T <= t|T> \tau, Z=0) for all t \in (\tau,\tau_{max}].

Value

A list with the following components:

• N: the total estimated number of active treatment recipients observed to be at risk at \tau

• nCases: the estimated number of clinical endpoint cases observed between \tau and \tau_{max} in the active treatment group

• nControls: the estimated number of controls observed to complete follow-up through \tau_{max} endpoint-free in the active treatment group

• nCasesWithS: the estimated number of clinical endpoint cases observed between \tau and \tau_{max} in the active treatment group with an available biomarker response

See Also

computePower

Examples

Nrand = 4100
tau = 3.5
taumax = 24
VEtauToTaumax = 0.75
VE0toTau = 0.75/2
risk0 = 0.034
dropoutRisk = 0.1
propCasesWithS = 1
computeN(Nrand, tau, taumax, VEtauToTaumax, VE0toTau, risk0, dropoutRisk, propCasesWithS)

Power Calculations for Assessing Intermediate Biomarkers as Correlates of Risk in the Active Treatment Group in Clinical Efficacy Trials, Accounting for Biomarker's Measurement Error and Treatment Efficacy

Description

Performs a power calculation for assessing a univariate dichotomous, trichotomous, or continuous intermediate biomarker response as a correlate of risk in the active treatment group in a clinical efficacy trial, accounting for the biomarker's measurement error and treatment efficacy. The statistical methods are described in [Gilbert, Janes, and Huang (2016). "Power/Sample Size Calculations for Assessing Correlates of Risk in Clinical Efficacy Trials."] Simulated data sets, extended to include placebo group and baseline immunogenicity predictor data, can be exported for harmonized assessment of biomarker-specific treatment efficacy.

Usage

computePower(
  nCasesTx,
  nControlsTx,
  nCasesTxWithS,
  controlCaseRatio = NULL,
  VEoverall,
  risk0,
  VElat0 = seq(0, VEoverall, len = 20),
  VElat1 = rep(VEoverall, 20),
  VElowest = NULL,
  Plat0 = NULL,
  Plat2 = NULL,
  P0 = Plat0,
  P2 = Plat2,
  PlatVElowest = NULL,
  sens = NULL,
  spec = NULL,
  FP0 = NULL,
  FN2 = NULL,
  M = 100,
  alpha = 0.05,
  sigma2obs = 1,
  rho = 1,
  biomType = c("continuous", "trichotomous", "dichotomous"),
  cohort = FALSE,
  p = NULL,
  tpsMethod = c("PL", "ML", "WL"),
  saveDir = NULL,
  saveFile = "CoRpower.RData",
  saveDataDir = NULL,
  saveDataFile = "fullData.RData",
  corr = NULL,
  nCasesPla = NULL,
  nControlsPla = NULL,
  sensBIP = NULL,
  specBIP = NULL,
  FP0BIP = NULL,
  FN2BIP = NULL,
  P0BIP = P0,
  P2BIP = P2
)

Arguments

Details

A number of calling arguments can be specified as vectors with each component specifying a distinct scenario for power assessment (saved in a separate .RData file). These are referred to as "varying arguments." Some varying arguments occur in a group, where the length and order of all specified vectors in the group must match; others are the only varying argument in their group. Only arguments belonging to a single group may be varied at a time; if two or more groups contain vector inputs, the function will treat such inputs as an error. The following are the groups of varying arguments that can be vectorized:

• nCasesTx, nControlsTx, and nCasesTxWithS (together with nCasesPla and nControlsPla if simulated data sets are to be saved)

• Plat0, Plat2, P0, and P2

• sens, spec, FP0, and FN2

• controlCaseRatio

• rho

• p

Arguments independent of biomarker type and sampling design: nCasesTx, nControlsTx, nCasesTxWithS, VEoverall, risk0, M, alpha, tpsMethod, saveDir, saveFile.

Arguments specific to a trichotomous (or dichotomous) biomarker response: VElat0, VElat1, Plat0, Plat2, P0, P2, biomType = "trichotomous" (or "dichotomous")

• Arguments for Approach 1: sens, spec, FP0, FN2

• Arguments for Approach 2: sigma2obs, rho

Arguments specific to a continuous biomarker response: VElowest, PlatVElowest, sigma2obs, rho, biomType = "continuous"

Arguments for a case-control without replacement sampling design: controlCaseRatio

Arguments for a case-cohort Bernoulli sampling design: cohort = TRUE, p

To save output from the power calculations in an .RData file, saveDir must be specified. The default file name is CoRpower.RData; a different file name may be specified by saveFile as a single character string, to which the value of the varying argument(s) will be appended for descriptive file naming purposes, or, alternatively, a character vector may be specified with full file names (a single file will be produced for each value of the varying argument(s)).

To link power calculations for detecting a correlate of risk and a correlate of treatment efficacy, simulated data sets used in the power calculations can be exported with placebo-group data, with a possible extension including BIP data, for harmonized use by methods assessing biomarker-specific treatment efficacy. The vignette "Algorithms for Simulating Placebo Group and Baseline Immunogenicity Predictor Data" provides more information on the algorithms and underlying assumptions for simulating placebo-group and BIP data. The exported data sets include treatment and placebo group data in the form of full rectangular data (i.e., disregarding biomarker sub-sampling), which enables the user to employ any preferred biomarker sub-sampling design. To generate and export such data, saveDataDir, nCasesPla, and nControlsPla must be specified. nCasesPla and nControlsPla must have the same length and order of components as nCasesTx, nControlsTx, and nCasesTxWithS.

If a BIP is to be included in the simulated data export, additional arguments are necessary. If the biomarker is trichotomous and Approach 1 is used, sensBIP, specBIP, FP0BIP, FN2BIP, P0BIP, and P2BIP must be specified; if the biomarker is trichotomous and Approach 2 is used, corr, P0BIP, and P2BIP must be specified; if the biomarker is continuous, corr must be specified.

Calling arguments pertaining to the simulation of the BIP in the exported data may also be specified as vectors, independently of the above varying arguments defining the power calculation scenarios for the active treatment group. Each component of these vectors results in the generation of a separate BIP variable, in the same order, in the output data. Some of these arguments occur in a group, where the length and order of all specified vectors in the group must match; others are the sole argument in their group. Only arguments belonging to a single group may be varied at a time; if two or more groups contain vector inputs, the function will treat such inputs as an error. The following are the groups of BIP arguments that can be vectorized:

• sensBIP, specBIP, FP0BIP, FN2BIP

• P0BIP, P2BIP

• corr

The default file name for the outputted data sets is fullData.RData. A different file name may be specified by saveDataFile as a single character string, to which the value of the "varying argument" for the power calculations will be appended for descriptive file naming purposes, or, alternatively, a character vector may be specified with full file names (a single file will be produced for each value of the varying argument(s)). Note: if the "varying argument" is controlCaseRatio or p, only one file will be generated because these arguments do not affect the simulation of the full data; therefore, saveDataFile must be a character string in these cases.

Value

If saveDir is specified, an output list (named pwr) for each power scenario is saved as an .RData file. Otherwise, the function returns a list of lists, where the outer list ranges over specified values of the varying argument(s) whose components denote distinct scenarios, and the inner list is the output list for each power scenario. For a dichotomous or trichotomous biomarker, each output list has the following components:

• power: a numeric vector of fractions of simulated trials in which the null hypothesis H_0 is rejected. Each value of the vector corresponds to a value in the grid of treatment (vaccine) efficacies specified by VElat0 and VElat1.

• RRt: a numeric vector of correlate-of-risk relative-risk effect sizes. Each value of the vector corresponds to a value in the grid of treatment (vaccine) efficacies specified by VElat0 and VElat1.

• risk1_2: a numeric vector of conditional endpoint risks given a high biomarker response in the active treatment group. Each value of the vector corresponds to a value in the grid of treatment (vaccine) efficacies specified by VElat0 and VElat1.

• risk1_0: a numeric vector of conditional endpoint risks given a low biomarker response in the active treatment group. Each value of the vector corresponds to a value in the grid of treatment (vaccine) efficacies specified by VElat0 and VElat1.

• VElat2: a numeric vector specifying a grid of treatment (vaccine) efficacy levels in the latent higher protected subgroup for a dichotomous or trichotomous biomarker

• VElat0: a numeric vector specifying a grid of treatment (vaccine) efficacy levels in the latent lower protected subgroup for a dichotomous or trichotomous biomarker

• Plat2: a numeric value specifying the prevalence of the latent higher protected subgroup for a dichotomous or trichotomous biomarker

• Plat0: a numeric value specifying the prevalence of the latent lower protected subgroup for a dichotomous or trichotomous biomarker

• P2: a numeric value specifying the probability of high biomarker response for a dichotomous or trichotomous biomarker

• P0: a numeric value specifying the probability of low biomarker response for a dichotomous or trichotomous biomarker

• alphaLat: a numeric vector of the log odds of the clinical endpoint in the subgroup of active treatment recipients with the latent x^{\ast}=0 (this coefficient estimate applies to a continuous biomarker)

• betaLat: a numeric vector of the log odds ratio of the clinical endpoint comparing two subgroups of active treatment recipients differing in the latent x^{\ast} by 1 (this coefficient estimate applies to a continuous biomarker)

• sens: a numeric vector of sensitivities (i.e., the probability of high biomarker response conditional on membership in the higher protected subgroup) of the observed dichotomous or trichotomous biomarker as a function of rho

• spec: a numeric vector of specificities (i.e., the probability of low biomarker response conditional on membership in the lower protected subgroup) of the observed dichotomous or trichotomous biomarker as a function of rho

• FP0: a numeric vector of false positive rates (i.e., the probability of high biomarker response conditional on membership in the lower protected subgroup) of the observed dichotomous or trichotomous biomarker as a function of rho

• FN2: a numeric vector of false negative rates (i.e., the probability of low biomarker response conditional on membership in the higher protected subgroup) of the observed dichotomous or trichotomous biomarker as a function of rho

• NcompleteTx: an integer value specifying nCasesTx + nControlsTx, i.e., the number, observed or projected, of active treatment recipients at risk at \tau with an observed endpoint or a completed follow-up through \tau_{max}

• nCasesTx: an integer value specifying the number of clinical endpoint cases observed (or projected) between \tau and \tau_{max} in the active treatment group

• nCasesTxWithS: an integer value specifying the number of clinical endpoint cases observed (or projected) between \tau and \tau_{max} in the active treatment group with an available biomarker response

• controlCaseRatio: an integer specifying the number of controls sampled per case for biomarker measurement in the without replacement case-control sampling design

• VEoverall: a numeric value specifying the overall treatment (vaccine) efficacy between \tau and \tau_{max}

• risk0: a numeric value specifying the overall placebo-group endpoint risk between \tau and \tau_{max}

• alpha: a numeric value specifying the two-sided Wald test type-I error rate

• rho: a numeric vector specifying distinct protection-relevant fractions of the variance of the observed biomarker

• approach: a number denoting whether Approach 1 or Approach 2 was used (1 if sens, spec, FP0, FN2 were specified in the input; 2 if rho and sigma2obs were specified in the input)

• varyingArg: a character string containing the name(s) and value(s) of the varying argument

For a continuous biomarker, each output list has the following components:

• power: a numeric vector of fractions of simulated trials in which the null hypothesis H_0 is rejected. Rows represent calculations for different values of rho or nCasesTx, depending on which is a vector. Columns represent calculations for the grid of treatment (vaccine) efficacy levels in the latent lowest-efficacy subgroup, specified by VElowest.

• RRc: a numeric vector of correlate-of-risk relative-risk effect sizes as a function of the grid of treatment (vaccine) efficacy levels in the latent lowest-efficacy subgroup, specified by VElowest

• betaLat: a numeric vector specifying the log odds ratio of the clinical endpoint comparing two subgroups of active treatment recipients differing in the latent x^{\ast} by 1 (this coefficient estimate applies to a continuous biomarker)

• alphaLat: a numeric vector specifying the the log odds of the clinical endpoint in the subgroup of active treatment recipients with the latent x^{\ast}=0 (this coefficient estimate applies to a continuous biomarker)

• PlatVElowest: a numeric value specifying the prevalence of the latent lowest-efficacy subgroup for a continuous biomarker

• VElowest: a numeric vector specifying a grid of treatment (vaccine) efficacy levels in the latent lowest-efficacy subgroup for a continuous biomarker

• sigma2obs: a numeric value specifying the variance of the observed continuous biomarker or of the dichotomous or trichotomous biomarker simulated using 'approach 2'

• NcompleteTx: an integer value specifying nCasesTx + nControlsTx, i.e., the number, observed or projected, of active treatment recipients at risk at \tau with an observed endpoint or a completed follow-up through \tau_{max}

• nCasesTx: an integer value specifying the number of clinical endpoint cases observed (or projected) between \tau and \tau_{max} in the active treatment group

• nCasesTxWithS: an integer value specifying the number of clinical endpoint cases observed (or projected) between \tau and \tau_{max} in the active treatment group with an available biomarker response

• controlCaseRatio: an integer value specifying the number of controls sampled per case for biomarker measurement in the without replacement case-control sampling design

• VEoverall: a numeric value specifying the overall treatment (vaccine) efficacy between \tau and \tau_{max}

• risk0: a numeric value specifying the overall placebo-group endpoint risk between \tau and \tau_{max}

• alpha: a numeric value specifying the two-sided Wald test type-I error rate

• rho: a numeric vector specifying distinct protection-relevant fractions of the variance of the observed biomarker

• varyingArg: a character string containing the name(s) and value(s) of the varying argument

If saveDataDir is specified, the simulated data, including placebo group and BIP data, are saved in one or more .RData file(s) containing a list of lists of data frames. The components of the outer list consist each of one Monte-Carlo iteration of simulated data for all values of VElat0 or VElat1 if the biomarker is trichotomous, or of VElowest if the biomarker is continuous. Each data frame corresponds to one simulated trial.

See Also

computeN, plotPowerTri, plotPowerCont

Examples

## Trichotomous biomarker, Approach 1, varying sens and spec ##
## Specify sens, spec, FP0, FN2
nCasesTx <- 32
nControlsTx <- 1000
nCasesTxWithS <- 32
controlCaseRatio <- 5
VEoverall <- 0.75
risk0 <- 0.034
VElat0 <- seq(0, VEoverall, len=20)  # 20 data points for the power curve
VElat1 <- rep(VEoverall, 20)
Plat0 <- 0.2
Plat2 <- 0.6
P0 <- Plat0  # different values of P0 can be set
P2 <- Plat2  # different values of P2 can be set
sens <- spec <- c(1, 0.9, 0.8, 0.7)
FP0 <- FN2 <- rep(0, 4)
M <- 5
alpha <- 0.05
biomType <- "trichotomous"
computePower(nCasesTx=nCasesTx, nControlsTx=nControlsTx, nCasesTxWithS=nCasesTxWithS,
             controlCaseRatio=controlCaseRatio, VEoverall=VEoverall,
             risk0=risk0, VElat0=VElat0, VElat1=VElat1, Plat0=Plat0,
             Plat2=Plat2, P0=P0, P2=P2, M=M, alpha=alpha, spec=spec,
             FP0=FP0, sens=sens, FN2=FN2, biomType=biomType)

## Not run: 
## Trichotomous biomarker, Approach 2, varying rho ##
## Saving simulated data (including placebo and BIP data)
## Specify rho, sigma2obs, saveDataDir, saveDataFile, corr

nCasesTx <- 32
nControlsTx <- 1000
nCasesTxWithS <- 32
controlCaseRatio <- 5
VEoverall <- 0.75
risk0 <- 0.034
VElat0 <- seq(0, VEoverall, len=20)
VElat1 <- rep(VEoverall, 20)
Plat0 <- 0.2
Plat2 <- 0.6
P0 <- Plat0
P2 <- Plat2
M <- 5
alpha <- 0.05
sigma2obs <- 1
rho <- c(1, 0.9, 0.7, 0.5)
biomType <- "trichotomous"
saveDataDir <- "~/myDir"
saveDataFile <- "myDataFile.RData"
corr <- 0.7
computePower(nCasesTx=nCasesTx, nControlsTx=nControlsTx, nCasesTxWithS=nCasesTxWithS,
             controlCaseRatio=controlCaseRatio, VEoverall=VEoverall, risk0=risk0,
             VElat0=VElat0, VElat1=VElat1, Plat0=Plat0, Plat2=Plat2, P0=P0, P2=P2,
             M=M, alpha=alpha, sigma2obs=sigma2obs, rho=rho, biomType=biomType,
             saveDataDir=saveDataDir, saveDataFile=saveDataFile, corr=corr)


## dichotomous biomarker, Approach 2, varying rho ##
## Plat0 + Plat2 = 1

nCasesTx <- 32
nControlsTx <- 1000
nCasesTxWithS <- 32
controlCaseRatio <- 5
VEoverall <- 0.75
risk0 <- 0.034
VElat0 <- seq(0, VEoverall, len=20)  # 20 data points for the power curve
VElat1 <- rep(0, 20)  # will not be used by function
Plat0 <- 0.25
Plat2 <- 1 - Plat0
P0 <- Plat0
P2 <- Plat2
M <- 5
alpha <- 0.05
sigma2obs <- 1
rho <- c(1, 0.9, 0.7, 0.5)
biomType <- "dichotomous"
computePower(nCasesTx=nCasesTx, nControlsTx=nControlsTx, nCasesTxWithS=nCasesTxWithS,
             controlCaseRatio=controlCaseRatio, VEoverall=VEoverall, risk0=risk0,
             VElat0=VElat0, VElat1=VElat1, Plat0=Plat0, Plat2=Plat2, P0=P0, P2=P2,
             M=M, alpha=alpha, sigma2obs=sigma2obs, rho=rho, biomType=biomType)


## Continuous biomarker, varying rho ##

nCasesTx <- 32
nControlsTx <- 1000
nCasesTxWithS <- 32
controlCaseRatio <- 5
VEoverall <- 0.75
risk0 <- 0.034
PlatVElowest <- 0.2
VElowest <- seq(0, VEoverall, len=20)
M <- 5
alpha <- 0.05
sigma2obs <- 1
rho <- c(1, 0.9, 0.7, 0.5)
biomType <- "continuous"
computePower(nCasesTx=nCasesTx, nControlsTx=nControlsTx, nCasesTxWithS=nCasesTxWithS,
             controlCaseRatio=controlCaseRatio, VEoverall=VEoverall, risk0=risk0,
             PlatVElowest=PlatVElowest, VElowest=VElowest, M=M, alpha=alpha,
             sigma2obs=sigma2obs, rho=rho, biomType=biomType)


## Continuous biomarker, case-cohort sampling design, varying p ##
nCasesTx <- 32
nControlsTx <- 1000
nCasesTxWithS <- 32
VEoverall <- 0.75
risk0 <- 0.034
PlatVElowest <- 0.2
VElowest <- seq(0, VEoverall, len=20)
M <- 5
alpha <- 0.05
sigma2obs <- 1
rho <- 0.9
biomType <- "continuous"
cohort <- TRUE
p <- c(0.01, 0.02, 0.03)
computePower(nCasesTx=nCasesTx, nControlsTx=nControlsTx, nCasesTxWithS=nCasesTxWithS,
             VEoverall=VEoverall, risk0=risk0, PlatVElowest=PlatVElowest,
             VElowest=VElowest, M=M, alpha=alpha, sigma2obs=sigma2obs,
             rho=rho, biomType=biomType, cohort=cohort, p=p)

## Continuous biomarker, saving output, varying sample sizes ##

nCasesTx <- 32
nControlsTx <- 1000
nCasesTxWithS <- 32
controlCaseRatio <- 5
VEoverall <- 0.75
risk0 <- 0.034
PlatVElowest <- 0.2
VElowest <- seq(0, VEoverall, len=20)
M <- 5
alpha <- 0.05
sigma2obs <- 1
rho <- c(1, 0.9, 0.7, 0.5)
biomType <- "continuous"
saveDir <- "~/myDir"
saveFile <- "MyFile.RData"
computePower(nCasesTx=nCasesTx, nCasesTxWithS=nCasesTxWithS, nControlsTx=nControlsTx,
             controlCaseRatio=controlCaseRatio, VEoverall=VEoverall,
             risk0=risk0, PlatVElowest=PlatVElowest, VElowest=VElowest,
             M=M, alpha=alpha, sigma2obs=sigma2obs, rho=rho,
             biomType=biomType, saveDir=saveDir, saveFile=saveFile)

## End(Not run)

Plotting of Power Curve versus Correlate of Risk Effect Size for Continuous Biomarkers

Description

Plots power (on the y-axis) to detect a correlate of risk effect size (on the x-axis) in the active treatment group for a continuous biomarker. The correlate of risk effect size is quantified as the odds ratio of the clinical endpoint comparing subgroups of active treatment recipients with a 1 standard deviation difference in a noise-free biomarker response.

Usage

plotPowerCont(
  outComputePower,
  outDir = NULL,
  legendText,
  legendTitle = NULL,
  extendedLeg = TRUE,
  verboseLeg = TRUE,
  margin = c(11, 7, 3, 1)
)

Arguments

Details

If multiple levels are specified for the biomarker measurement error input argument rho, only the first level is used to determine the RR_c values shown as x-axis tickmark labels.

The function's plot can be interpreted in conjunction with the output of plotVElatCont by matching the CoR relative risk in the two plots and examining power compared to treatment (vaccine) efficacy. This sheds light on the importance of overall vaccine efficacy on power and allows correlates of risk results to be interpreted in terms of potential correlates of efficacy/protection.

Value

None. The function is called solely for plot generation.

References

Gilbert P. B., Janes H., and Huang Y. (2016), Power/Sample Size Calculations for Assessing Correlates of Risk in Clinical Efficacy Trials. Stat Med 35(21):3745-59.

See Also

computePower, plotVElatCont, plotPowerTri

Examples

# Example scenario with continuous biomarker, where values of rho are varied

# Set input parameters for computePower function
nCasesTx <- 10
nControlsTx <- 300
nCasesTxWithS <- 10
controlCaseRatio <- 5
VEoverall <- 0.75
risk0 <- 0.034
PlatVElowest <- 0.2
VElowest <- seq(0, VEoverall, len=5)
Plat0 <- P0 <- 0.2
Plat2 <- P2 <- 0.6
M <- 22
alpha <- 0.05
sigma2obs <- 1
rho <- c(1, 0.7, 0.4)
biomType <- "continuous"

# Output from computePower function is stored in an object as a list of lists
pwr <- computePower(nCasesTx=nCasesTx, nCasesTxWithS=nCasesTxWithS, nControlsTx=nControlsTx,
                    controlCaseRatio=controlCaseRatio, risk0=risk0, VEoverall=VEoverall,
                    PlatVElowest=PlatVElowest, VElowest=VElowest,
                    Plat0=Plat0, Plat2=Plat2, P0=P0, P2=P2, M=M, alpha=alpha,
                    sigma2obs=sigma2obs, rho=rho, biomType=biomType)

# Set parameters for plotPowerCont function
# outComputePower is a list of lists containing output from the computePower function
outComputePower <- pwr
legendText <- paste0("rho = ", c(1, 0.7, 0.4))
plotPowerCont(outComputePower=outComputePower, legendText=legendText)

## Not run: 
# Output from computePower function is saved in RData files
computePower(..., saveDir = "myDir", saveFile = "myFile.RData")
# outComputePower is a character string specifying the file containing the
# computePower output
# outDir is a character string specifying the outComputePower file directory
outComputePower <- paste0("myFile_rho_", c(1, 0.7, 0.4), ".RData")
outDir <- "~/myDir"
legendText <- paste0("rho = ", c(1, 0.7, 0.4))
plotPowerCont(outComputePower, outDir=outDir, legendText = legendText)

## End(Not run)

Plotting of Power versus Correlate of Risk Effect Size for Dichotomous and Trichotomous Biomarkers

Description

Plots power (on the y-axis) to detect a correlate of risk effect size (on the x-axis) in the active treatment group for a dichotomous or trichotomous biomarker. The correlate of risk effect size is quantified as the relative risk of the clinical endpoint comparing subgroups of active treatment recipients with high and low biomarker response.

Usage

plotPowerTri(
  outComputePower,
  outDir = NULL,
  legendText,
  legendTitle = NULL,
  extendedLeg = TRUE,
  verboseLeg = TRUE,
  margin = c(11, 7, 3, 1)
)

Arguments

Details

If multiple levels are specified for the biomarker measurement error input parameters (i.e., for sens/spec or rho) in computePower, only the first level is used to determine the RR_t values shown as x-axis tickmark labels.

Value

None. The function is called solely for plot generation.

References

Gilbert P. B., Janes H., and Huang Y. (2016), Power/Sample Size Calculations for Assessing Correlates of Risk in Clinical Efficacy Trials. Stat Med 35(21):3745-59.

See Also

computePower, plotPowerCont

Examples

# Example scenario with trichotomous biomarker, where values of controlCaseRatio are varied

# Set input parameters for computePower function
nCasesTx <- 10
nControlsTx <- 300
nCasesTxWithS <- 10
controlCaseRatio <- c(5,3)
VEoverall <- 0.75
risk0 <- 0.034
VElat0 <- seq(0, VEoverall, len=5)
VElat1 <- rep(VEoverall, 5)
Plat0 <- P0 <- 0.2
Plat2 <- P2 <- 0.6
sens <- spec <- 0.8
FP0 <- FN2 <- 0
M <- 50
alpha <- 0.05
biomType <- "trichotomous"

# Output from computePower function is stored in an object as a list of lists
pwr <- computePower(nCasesTx=nCasesTx, nControlsTx=nControlsTx, nCasesTxWithS=nCasesTxWithS,
                     controlCaseRatio=controlCaseRatio, risk0=risk0,
                     VEoverall=VEoverall, Plat0=Plat0, Plat2=Plat2, P0=P0, P2=P2,
                     VElat0=VElat0, VElat1=VElat1, M=M, alpha=alpha, spec=spec,
                     FP0=FP0, sens=sens, FN2=FN2, biomType=biomType)

# Set parameters for plotPowerTri function
# outComputePower is a list of lists containing outputs from the computePower function
outComputePower <- pwr
legendText <- paste0("controls:cases = ", c("5:1","3:1"))
plotPowerTri(outComputePower=outComputePower, legendText=legendText)

## Not run: 
# outComputePower is a character vector specifying the files containing computePower output
# outDir is a character vector specifying the outComputePower file directories
outComputePower <- paste0("myFile_controlCaseRatio_", c(5, 3), ".RData")
outDir <- rep("~/myDir", 2)
legendText <- paste0("controls:cases = ", c("5:1","3:1"))
plotPowerTri(outComputePower, outDir=outDir, legendText = legendText)

## End(Not run)

Plotting of ROC Curves for Trichotomous Biomarkers

Description

Plots the receiver operating characteristic (ROC) curve displaying sensitivity and specificity for a range of P2 and P0 values, four values of rho, and four values of Plat2. Illustrates how different levels of measurement error rho map to sensitivity and specificity, depending on the value of Plat2. This funciton is used to create Figure 1 in the Supplementary Material of [Gilbert, Janes, and Huang (2016). "Power/Sample Size Calculations for Assessing Correlates of Risk in Clinical Efficacy Trials."]

Usage

plotROCcurveTri(Plat0, Plat2, P0, P2, rho)

Arguments

Value

None. The function is called solely for plot generation.

Examples

Plat0 <- 0.2
Plat2 <- c(0.2, 0.3, 0.4, 0.5)
P0 <- seq(0.90, 0.10, len=10)
P2 <- seq(0.10, 0.90, len=10)
rho <- c(1, 0.9, 0.7, 0.5)
plotROCcurveTri(Plat0 = Plat0, Plat2 = Plat2, P0 = P0, P2 = P2, rho = rho)

Plotting of the Ratio of Relative Risks for Higher/Lower Latent Subgroups against Correlate of Risk Effect Size for Trichotomous Biomarkers

Description

Plots the ratio of relative risks for the higher and lower latent subgroups (on the y-axis) versus the correlate of risk effect size (on the x-axis) in the active treatment group for a trichotomous biomarker. The correlate of risk effect size is quantified as the relative risk ratio of the clinical endpoint comparing subgroups of active treatment recipients with high and low biomarker response.

Usage

plotRRgradVE(
  outComputePower,
  outDir = NULL,
  legendText,
  extendedLeg = TRUE,
  xLegPos = 0.5,
  yLegPos = 0.5,
  ySep = 0.07,
  margin = c(7, 4, 3, 1)
)

Arguments

Details

When rho is varied, this plot shows how the relationship between the correlate of risk effect size and the relative risks for the higher and lower latent subgroups changes for different values of rho. The ratio of relative risks for the higher and lower latent subgroups is a relative vaccine efficacy parameter. When rho=1, a correlate of risk in the vaccine group is equivalent to the relative vaccine efficacy parameter, whereas for imperfectly measured biomarkers with rho<1, the correlate of risk effect size is closer to the null than the relative vaccine efficacy parameter is.

Value

None. The function is called solely for plot generation.

See Also

computePower, plotPowerTri

Examples

# Example scenario with trichotomous biomarker, where values of rho are varied

# Set input parameters for computePower function
nCasesTx <- 10
nControlsTx <- 300
nCasesTxWithS <- 10
controlCaseRatio <- 3
VEoverall <- 0.75
risk0 <- 0.034
VElat0 <- seq(0, VEoverall, len=10)
VElat1 <- rep(VEoverall, 10)
Plat0 <- P0 <- 0.2
Plat2 <- P2 <- 0.6
M <- 20
alpha <- 0.05
sigma2obs <- 1
rho <- c(1, 0.7, 0.4)
biomType <- "trichotomous"

# Output from computePower function is stored in an object as a list
pwr <- computePower(nCasesTx=nCasesTx, nControlsTx=nControlsTx, nCasesTxWithS=nCasesTxWithS,
                    controlCaseRatio=controlCaseRatio, risk0=risk0, VEoverall=VEoverall,
                    Plat0=Plat0, Plat2=Plat2, P0=P0, P2=P2, VElat0=VElat0,
                    VElat1=VElat1, M=M, alpha=alpha, sigma2obs=sigma2obs, rho=rho,
                    biomType=biomType)

# Set parameters for plotPowerCont function
# outComputePower is a list of lists containing output from the computePower function
outComputePower <- pwr
legendText <- paste0("rho = ", c(1, 0.7, 0.4))
plotRRgradVE(outComputePower=outComputePower, legendText=legendText)

## Not run: 
# Output from computePower function is saved in an RData file
computePower(..., saveDir = "myDir", saveFile = "myFile.RData")

# outComputePower is a character string specifying the file containing the computePower output
# outDir is a character string specifying the outComputePower file directory
outComputePower <- paste0("myFile_rho_", c(1, 0.7, 0.4), ".RData")
outDir <- "~/myDir"
legendText <- paste0("rho = ", c(1, 0.7, 0.4))
plotRRgradVE(outComputePower, outDir=outDir, legendText = legendText)

## End(Not run)

Plotting Treatment (Vaccine) Efficacy Curves for Different Correlate of Risk Relative Risks for Continuous Biomarkers

Description

Plots the treatment (vaccine) efficacy curve for the true latent biomarker for eight different values of the latent correlate of risk relative risk and the lowest vaccine efficacy level for the true biomarker. All curves assume rho=1, and treatment (vaccine) efficacy ranges from 0 to 1. The legend is completely determined by the function.

Usage

plotVElatCont(outComputePower, outDir = NULL)

Arguments

Details

computePower function input parameter VElowest must have length greater than or equal to eight for all eight scenarios to have unique RRc and VElowest. Otherwise, only length(VElowest) unique VE curves will be displayed.

When interpreting the output of the function, the null hypothesis corresponds to a flat curve where vaccine efficacy for all values of the true latent biomarker is equal to the overall vaccine efficacy. Increasing departures from the null hypothesis correspond to increasingly variable and steep VE curves. The output assumes the overall placebo-group endpoint risk between \tau and \tau_{max} is constant for all values of the latent and observed biomarker and that there is no measurement error (\rho=1). When this is the case, an association of the biomarker with infection risk in the vaccine group (a correlate of risk) is equivalent to an association of the biomarker with treatment (vaccine) efficacy.

The function's plot can also be interpreted in conjunction with the output of the plotPowerCont function by matching the CoR relative risk in the two plots and examining power compared to VE. This sheds light on the importance of overall VE on power and further enables correlates of risk results to be interpreted in terms of potential correlates of efficacy/protection.

Value

None. The function is called solely for plot generation.

See Also

computePower, plotPowerCont

Examples

# Example scenario with continuous biomarker, where values of rho are varied

# Set input parameters for computePower function
nCasesTx <- 10
nControlsTx <- 300
nCasesTxWithS <- 10
controlCaseRatio <- 3
VEoverall <- 0.75
risk0 <- 0.034
PlatVElowest <- 0.2
VElowest <- seq(0, VEoverall, len=8)
Plat0 <- P0 <- 0.2
Plat2 <- P2 <- 0.6
M <- 13
alpha <- 0.05
sigma2obs <- 1
rho <- 1
biomType <- "continuous"

# Output from computePower function is stored in an object as a list
pwr <- computePower(nCasesTx=nCasesTx, nControlsTx=nControlsTx, nCasesTxWithS=nCasesTxWithS,
                    controlCaseRatio=controlCaseRatio, risk0=risk0, VEoverall=VEoverall,
                    PlatVElowest=PlatVElowest, VElowest=VElowest, Plat0=Plat0, Plat2=Plat2,
                    P0=P0, P2=P2, M=M, alpha=alpha, sigma2obs=sigma2obs, rho=rho, biomType=biomType)

# Set parameters for plotPowerCont function
# outComputePower is a list containing output from the computePower function
outComputePower <- pwr
plotVElatCont(outComputePower=outComputePower)

## Not run: 
# Output from computePower function is saved in an RData file
computePower(..., saveDir = "myDir", saveFile = "myFile.RData")
# outComputePower is a character string specifying the file containing the computePower output
# outDir is a character string specifying the outComputePower file directory
outComputePower <- "myFile.RData"
outDir <- "~/myDir"
plotVElatCont(outComputePower, outDir=outDir)

## End(Not run)