A class to encapsulate the adaptive clinical trial design of Lai, Lavori and Liao

Description

ASSISTDesign objects are used to design, simulate and analyze adaptive group sequential clinical trial with three stages. For details refer to the paper Adaptive Choice of Patient Subgroup for Comparing Two Treatments by Tze Leung Lai and Philip W. Lavori and Olivia Yueh-Wen Liao. Contemporary Clinical Trials, Vol. 39, No. 2, pp 191-200 (2014).

Methods

Public methods

• ASSISTDesign$new()

• ASSISTDesign$getDesignParameters()

• ASSISTDesign$getTrialParameters()

• ASSISTDesign$getBoundaries()

• ASSISTDesign$setBoundaries()

• ASSISTDesign$print()

• ASSISTDesign$computeCriticalValues()

• ASSISTDesign$explore()

• ASSISTDesign$performInterimLook()

• ASSISTDesign$analyze()

• ASSISTDesign$summary()

• ASSISTDesign$clone()

Method new()

Create a new ASSISTDesign instance using the parameters specified.

Usage

ASSISTDesign$new(
  designParameters,
  trialParameters,
  discreteData = FALSE,
  boundaries
)

Arguments

Returns

a new AssistDesign object

Method getDesignParameters()

return the designParameters field

Usage

ASSISTDesign$getDesignParameters()

Method getTrialParameters()

return the trialParameters field

Usage

ASSISTDesign$getTrialParameters()

Method getBoundaries()

return the boundaries field

Usage

ASSISTDesign$getBoundaries()

Method setBoundaries()

Set the boundaries field

Usage

ASSISTDesign$setBoundaries(value)

Arguments

Method print()

Print details of the design to console

Usage

ASSISTDesign$print()

Method computeCriticalValues()

Compute the critical boundary values \tilde{b}, b and c for futility, efficacy and final efficacy decisions. This is time consuming so cache where possible.

Usage

ASSISTDesign$computeCriticalValues()

Returns

a named vector of critical values with names btilde, b, and c as in the paper

Method explore()

Explore the design using the specified number of simulations and random number seed and other parameters.

Usage

ASSISTDesign$explore(
  numberOfSimulations = 5000,
  rngSeed = 12345,
  trueParameters = self$getDesignParameters(),
  recordStats = TRUE,
  showProgress = TRUE,
  fixedSampleSize = FALSE,
  saveRawData = FALSE
)

Arguments

Returns

a list of results

Method performInterimLook()

Perform an interim look on trial data

Usage

ASSISTDesign$performInterimLook(
  trialData,
  stage,
  recordStats = FALSE,
  fixedSampleSize = FALSE
)

Arguments

Returns

the trial history

Method analyze()

Analyze the exploration data from trial

Usage

ASSISTDesign$analyze(trialExploration)

Arguments

Returns

Return a list of summary quantities

Method summary()

Print the operating characteristics of the design using the analysis data

Usage

ASSISTDesign$summary(analysis)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

ASSISTDesign$clone(deep = FALSE)

Arguments

See Also

LLL.SETTINGS for an explanation of trial parameters

Examples

## Not run: 
data(LLL.SETTINGS)
prevalence <- LLL.SETTINGS$prevalences$table1
scenario <- LLL.SETTINGS$scenarios$S0
designParameters <- list(prevalence = prevalence,
                         mean = scenario$mean,
                         sd = scenario$sd)
designA <- ASSISTDesign$new(trialParameters = LLL.SETTINGS$trialParameters,
                              designParameters = designParameters)
print(designA)
result <- designA$explore(showProgress = interactive())
analysis <- designA$analyze(result)
designA$summary(analysis)

## End(Not run)

A fixed sample design to compare against the adaptive clinical trial design

Description

ASSISTDesignB objects are used to design a trial with certain characteristics provided in the object instantiation method. This design differs from ASSISTDesign in only how it computes the critical boundaries, how it performs the interim look, and what quantities are computed in a trial run.

Super class

ASSISTant::ASSISTDesign -> ASSISTDesignB

Methods

Public methods

• ASSISTDesignB$computeCriticalValues()

• ASSISTDesignB$explore()

• ASSISTDesignB$analyze()

• ASSISTDesignB$summary()

• ASSISTDesignB$clone()

Method computeCriticalValues()

Compute the critical boundary value c_\alpha

Usage

ASSISTDesignB$computeCriticalValues()

Returns

a named vector of a single value containing the value for c

Method explore()

Explore the design using the specified number of simulations, random number seed, and further parameters.

Usage

ASSISTDesignB$explore(
  numberOfSimulations = 100,
  rngSeed = 12345,
  trueParameters = self$getDesignParameters(),
  showProgress = TRUE,
  saveRawData = FALSE
)

Arguments

Returns

a list of results

Method analyze()

Analyze the exploration data from trial

Usage

ASSISTDesignB$analyze(trialExploration)

Arguments

Returns

Return a list of summary quantities

Method summary()

Print the operating characteristics of the design using the analysis data

Usage

ASSISTDesignB$summary(analysis)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

ASSISTDesignB$clone(deep = FALSE)

Arguments

See Also

ASSISTDesign which is a superclass of this object

Examples

## Not run: 
data(LLL.SETTINGS)
prevalence <- LLL.SETTINGS$prevalences$table1
scenario <- LLL.SETTINGS$scenarios$S0
designParameters <- list(prevalence = prevalence,
                       mean = scenario$mean,
                       sd = scenario$sd)
designB <- ASSISTDesignB$new(trialParameters = LLL.SETTINGS$trialParameters,
                            designParameters = designParameters)
print(designB)
## A realistic design uses 5000 simulations or more!
result <- designB$explore(showProgress = interactive())
analysis <- designB$analyze(result)
designB$summary(analysis)

## End(Not run)
## For full examples, try:
## browseURL(system.file("full_doc/ASSISTant.html", package="ASSISTant"))

A fixed sample RCT design to compare against the adaptive clinical trial design of Lai, Lavori and Liao.

Description

ASSISTDesignC objects are used to design a trial with certain characteristics provided in the object instantiation method. This design differs from ASSISTDesign in only how it computes the critical boundaries, how it performs the interim look, and what quantities are computed in a trial run.

Super classes

ASSISTant::ASSISTDesign -> ASSISTant::ASSISTDesignB -> ASSISTDesignC

Methods

Public methods

• ASSISTDesignC$computeCriticalValues()

• ASSISTDesignC$explore()

• ASSISTDesignC$analyze()

• ASSISTDesignC$summary()

• ASSISTDesignC$clone()

Method computeCriticalValues()

Compute the critical boundary values \tilde{b}, b and c for futility, efficacy and final efficacy decisions. This is time consuming so cache where possible.

Usage

ASSISTDesignC$computeCriticalValues()

Returns

a named list containing the critical value cAlpha

Method explore()

Explore the design using the specified number of simulations and random number seed and other parameters.

Usage

ASSISTDesignC$explore(
  numberOfSimulations = 5000,
  rngSeed = 12345,
  trueParameters = self$getDesignParameters(),
  showProgress = TRUE,
  saveRawData = FALSE
)

Arguments

Returns

a list of results

Method analyze()

Analyze the design given the trialExploration data

Usage

ASSISTDesignC$analyze(trialExploration)

Arguments

Returns

a named list of rejections

Method summary()

Print the operating characteristics of the design using the analysis data

Usage

ASSISTDesignC$summary(analysis)

Arguments

Returns

no value, just print

Method clone()

The objects of this class are cloneable with this method.

Usage

ASSISTDesignC$clone(deep = FALSE)

Arguments

See Also

ASSISTDesignB which is a superclass of this object

Examples

data(LLL.SETTINGS)
prevalence <- LLL.SETTINGS$prevalences$table1
scenario <- LLL.SETTINGS$scenarios$S0
designParameters <- list(prevalence = prevalence,
                       mean = scenario$mean,
                       sd = scenario$sd)
## A realistic design uses 5000 simulations or more!
designC <- ASSISTDesignC$new(trialParameters = LLL.SETTINGS$trialParameters,
                            designParameters = designParameters)
print(designC)
result <- designC$explore(numberOfSimulations = 100, showProgress = interactive())
analysis <- designC$analyze(result)
designC$summary(analysis)
## For full examples, try:
## browseURL(system.file("full_doc/ASSISTant.html", package="ASSISTant"))

Three stage group sequential adaptive design with subgroup selection

Description

ASSISTant is a package that implements a three-stage adaptive clinical trial design with provision for subgroup selection where the treatment may be effective; see Lai, Lavori and Liao (doi:10.1016/j.cct.2014.09.001). The main design object is an R6 class that can be instantiated and manipulated to obtain the operating characteristics. A vignette is provided showing the use of this package for designing the DEFUSE-3 trial, described in the paper by Lai, Lavori and Liao. The package contains everything necessary to reproduce the results of the paper.

References

Adaptive Choice of Patient Subgroup for Comparing Two Treatments by Tze Leung Lai and Philip W. Lavori and Olivia Yueh-Wen Liao. Contemporary Clinical Trials, Vol. 39, No. 2, pp 191-200 (2014, doi:10.1016/j.cct.2014.09.001).

Adaptive design of confirmatory trials: Advances and challenges by Tze Leung Lai and Philip W. Lavori and Ka Wai Tsang. Contemporary Clinical Trials, Vol. 45, Part A, pp 93-102 (2015, doi:10.1016/j.cct.2015.06.007).

The DEFUSE3 design

Description

DEFUSE3Design is a slight variant of the the adaptive clinical trial design of Lai, Lavori and Liao. Simulation is used to compute the expected maximum sample size and the boundary for early futility is adjusted to account as well.

Super class

ASSISTant::ASSISTDesign -> DEFUSE3Design

Methods

Public methods

• DEFUSE3Design$getOriginalBoundaries()

• DEFUSE3Design$new()

• DEFUSE3Design$adjustCriticalValues()

• DEFUSE3Design$explore()

• DEFUSE3Design$performInterimLook()

• DEFUSE3Design$clone()

Method getOriginalBoundaries()

Return the original boundaries for the design

Usage

DEFUSE3Design$getOriginalBoundaries()

Returns

a named vector of values for b, btilde and c

Method new()

Create a DEFUSE3Design object

Usage

DEFUSE3Design$new(
  designParameters,
  trialParameters,
  discreteData = FALSE,
  numberOfSimulations = 5000,
  rngSeed = 54321,
  showProgress = TRUE,
  trueParameters = NULL,
  boundaries
)

Arguments

Returns

a new AssistDesign object

Method adjustCriticalValues()

Adjust critical values to account for sample size loss due to futility

Usage

DEFUSE3Design$adjustCriticalValues(numberOfSimulations, rngSeed, showProgress)

Arguments

Returns

the adjusted boundaries

Method explore()

Explore the design using the specified number of simulations and random number seed and other parameters.

Usage

DEFUSE3Design$explore(
  numberOfSimulations = 5000,
  rngSeed = 12345,
  trueParameters = self$getDesignParameters(),
  recordStats = TRUE,
  showProgress = TRUE,
  saveRawData = FALSE
)

Arguments

Returns

a list of results

Method performInterimLook()

Perform an interim look for futility

Usage

DEFUSE3Design$performInterimLook(trialData, stage, recordStats = FALSE)

Arguments

Returns

the trial history

Method clone()

The objects of this class are cloneable with this method.

Usage

DEFUSE3Design$clone(deep = FALSE)

Arguments

See Also

ASSISTDesign which is a superclass of this object

Examples

trialParameters <- list(N = c(200, 340, 476), type1Error = 0.025,
                        eps = 1/2, type2Error = 0.1)
designParameters <- list(
   nul0 = list(prevalence = rep(1/6, 6), mean = matrix(0, 2, 6),
               sd = matrix(1, 2, 6)),
   alt1 = list(prevalence = rep(1/6, 6), mean = rbind(rep(0, 6),
               c(0.5, 0.4, 0.3, 0, 0, 0)),
               sd = matrix(1, 2, 6)),
   alt2 = list(prevalence = rep(1/6, 6), mean = rbind(rep(0, 6),
               c(0.5, 0.5, 0, 0, 0, 0)),
               sd = matrix(1,2, 6)),
   alt3 = list(prevalence = rep(1/6, 6), mean = rbind(rep(0, 6), rep(0.36, 6)),
               sd = matrix(1,2, 6)),
   alt4 = list(prevalence = rep(1/6, 6), mean = rbind(rep(0, 6), rep(0.30, 6)),
               sd = matrix(1,2, 6)),
   alt5 = list(prevalence = rep(1/6, 6), mean = rbind(rep(0, 6),
               c(0.4, 0.3, 0.2, 0, 0, 0)),
               sd = matrix(1,2, 6)),
   alt6 = list(prevalence = rep(1/6, 6), mean = rbind(rep(0, 6),
               c(0.5, 0.5, 0.3, 0.3, 0.1, 0.1)),
               sd = matrix(1,2, 6)))

## Not run: 
## A realistic design uses 5000 simulations or more!
defuse3 <- DEFUSE3Design$new(trialParameters = trialParameters,
                             numberOfSimulations = 25,
                             designParameters = designParameters$nul0,
                             showProgress = FALSE)
print(defuse3)
result <- defuse3$explore(showProgress = interactive())
analysis <- defuse3$analyze(result)
print(defuse3$summary(analysis))

## End(Not run)
## For full examples, try:
## browseURL(system.file("full_doc/defuse3.html", package="ASSISTant"))

Design and trial settings used in the Lai, Lavori, Liao paper simulations

Description

A list of design and trial design settings used for analysis and simulations in the Lai, Lavori, Liao paper displayed in Tables 1 and 2. The elements of the list are the following

trialParameters

N

the sample size at each of three interim looks, the last being the final one; The length of this also determines the number of interim looks

type1Error

the overall type I error

eps

the fraction of type I error spent at each interim look

type2Error

the type II error desired

scenarios

A list of the 10 settings used in the simulations named S0, S1, ..., S10 as in the paper, each with three elements

mean

a 2\times J matrix of means, the first row for the null setting, the second for the alternative

sd

a 2\times J matrix of standard deviations, the first row for the null setting, the second for the alternative

prevalences

A list of two elements with prevalence vectors used in the paper; the lengths of these vectors implicitly define the number of groups.

table1

a vector of equal prevalences for six groups used in table 1

table2

a vector of prevalences used in table 2 of the paper

References

Adaptive Choice of Patient Subgroup for Comparing Two Treatments by Tze Leung Lai and Philip W. Lavori and Olivia Yueh-Wen Liao. Contemporary Clinical Trials, Vol. 39, No. 2, pp 191-200 (2014, doi:10.1016/j.cct.2014.09.001).

Return a vector of column names for statistics for a given stage

Description

Return a vector of column names for statistics for a given stage

Usage

colNamesForStage(stage, J)

Arguments

Value

a character vector of the column names

Compute the three modified Haybittle-Peto boundaries

Description

Compute the three modified Haybittle-Peto boundaries

Usage

computeMHPBoundaries(prevalence, N, alpha, beta, eps, futilityOnly = FALSE)

Arguments

Value

a named vector of three values containing \tilde{b}, b, c

Compute the three modified Haybittle-Peto boundaries and effect size

Description

Compute the three modified Haybittle-Peto boundaries and effect size

Usage

computeMHPBoundaryITT(prevalence, alpha)

Arguments

Value

a named vector of a single value containing the value for c

Compute the mean and sd of a discrete Rankin distribution

Description

Compute the mean and sd of a discrete Rankin distribution

Usage

computeMeanAndSD(probVec = rep(1, 7L), support = 0L:6L)

Arguments

Value

a named vector of mean and sd

Conform designParameters so that weights are turned in to probabilities, the null and control distributions are proper matrices etc.

Description

Conform designParameters so that weights are turned in to probabilities, the null and control distributions are proper matrices etc.

Usage

conformParameters(plist, discreteData = FALSE)

Arguments

Value

the modified parameter list

A data generation function using a discrete distribution for Rankin score rather than a normal distribution

Description

A data generation function using a discrete distribution for Rankin score rather than a normal distribution

Usage

generateDiscreteData(prevalence, N, support = 0L:6L, ctlDist, trtDist)

Arguments

Value

a three-column data frame of subGroup, trt (0 or 1), and score

Examples

# Simulate data from a discrete distribution for the Rankin scores,
# which are typically ordinal integers from 0 to 6 in the following
# simulations. So we define a few scenarios.
library(ASSISTant)
null.uniform <- rep(1, 7L) ## uniform on 7 support points
hourglass <- c(1, 2, 2, 1, 2, 2, 1)
inverted.hourglass <- c(2, 1, 1, 2, 1, 1, 2)
bottom.heavy <- c(2, 2, 2, 1, 1, 1, 1)
bottom.heavier <- c(3, 3, 2, 2, 1, 1, 1)
top.heavy <- c(1, 1, 1, 1, 2, 2, 2)
top.heavier <- c(1, 1, 1, 2, 2, 3, 3)
ctlDist <- null.uniform
trtDist <- cbind(null.uniform, null.uniform, hourglass, hourglass) ## 4 groups
generateDiscreteData(prevalence = rep(1, 4), N = 10, ctlDist = ctlDist,
                     trtDist = trtDist) ## default support is 0:6
trtDist <- cbind(bottom.heavy, bottom.heavy, top.heavy, top.heavy)
generateDiscreteData(prevalence = rep(1, 4), N = 10, ctlDist = ctlDist,
                     trtDist = trtDist)
support <- c(-2, -1, 0, 1, 2) ## Support of distribution
top.loaded <- c(1, 1, 1, 3, 3) ## Top is heavier
ctl.dist <- c(1, 1, 1, 1, 1) ## null on 5 support points
trt.dist <- cbind(ctl.dist, ctl.dist, top.loaded) ## 3 groups
generateDiscreteData(prevalence = rep(1, 3), N = 10, support = support,
                     ctlDist = ctl.dist, trtDist = trt.dist)
## ctl.dist can also be a matrix with different nulls for each subgroup
uniform <- rep(1, 5)
bot.loaded <- c(3, 3, 1, 1, 1)
ctl.dist <- matrix(c(uniform, bot.loaded, top.loaded), nrow = 5)
generateDiscreteData(prevalence = rep(1, 3), N = 10, support = support,
                     ctlDist = ctl.dist, trtDist = trt.dist)

A data generation function along the lines of what was used in the Lai, Lavori, Liao paper. score rather than a normal distribution

Description

A data generation function along the lines of what was used in the Lai, Lavori, Liao paper. score rather than a normal distribution

Usage

generateNormalData(prevalence, N, mean, sd)

Arguments

Value

a three-column data frame of subGroup, trt (0 or 1), and score

Compute the sample size for any group at a stage assuming a nested structure as in the paper.

Description

In the three stage design under consideration, the groups are nested with assumed prevalences and fixed total sample size at each stage. This function returns the sample size for a specified group at a given stage, where the futility stage for the overall group test may be specified along with the chosen subgroup.

Usage

groupSampleSize(
  prevalence,
  N,
  stage,
  group,
  HJFutileAtStage = NA,
  chosenGroup = NA
)

Arguments

Value

the sample size for group

Compute the efficacy boundary (modified Haybittle-Peto) for the first two stages

Description

Compute the efficacy boundary (modified Haybittle-Peto) for the first two stages

Usage

mHP.b(prevalence, N, cov.J, mu.prime, Sigma.prime, alpha, btilde, theta)

Arguments

Compute the futility boundary (modified Haybittle-Peto) for the first two stages

Description

The futility boundary \tilde{b} is computed by solving (under the alternative)

Usage

mHP.btilde(beta, cov.J)

Arguments

Details

P(\tilde{Z}_J^1\le\tilde{b} or \tilde{Z}_J^2\le\tilde{b}) = \epsilon\beta

where the superscripts denote the stage and \epsilon is the fraction of the type I error (\alpha) spent and \beta is the type II error. We make use of the joint normal density of Z_{J} (the overall group) at each of the three stages and the fact that the \tilde{Z_J} is merely a translation of Z_J. So here the calculation is based on a mean of zero and has to be translated during use!

Compute the efficacy boundary (modified Haybittle-Peto) for the final (third) stage

Description

Compute the efficacy boundary (modified Haybittle-Peto) for the final (third) stage

Usage

mHP.c(prevalence, N, cov.J, mu.prime, Sigma.prime, alpha, btilde, b, theta)

Arguments

Is a scalar quantity is a specified range?

Description

Check if the argument is a scalar within specified range

Check if the argument is within specified range

Check if the argument is a scalar integer within specified range

Check if the argument is an integer vector within specified range

The computation involves a J-1 multivariate normal integral of the conditional density of the i-th subgroup statistic given that it was maximal among all subgroups:

Usage

scalarInRange(x, low = -Inf, high = Inf)

numberInRange(x, low = -Inf, high = Inf)

scalarIntegerInRange(x, low = -Inf, high = Inf)

integerInRange(x, low = -Inf, high = Inf)

den.vs(v, i, mu.prime, Sigma.prime, fut)

Arguments

Details

\phi_i(v)(\int_0^v\int_0^v\ldots \int_0^{\tilde{b}} \phi_v(z_{-i})dz_{-i})

where z_{-i} denotes all subgroups other than i.

Value

TRUE or FALSE

TRUE or FALSE

TRUE or FALSE

TRUE or FALSE

the conditional probability

Compute the standardized Wilcoxon test statistic for two samples

Description

We compute the standardized Wilcoxon test statistic with mean 0 and and standard deviation 1 for samples x and y. The R function stats::wilcox.test() returns the statistic

Usage

wilcoxon(x, y, theta = 0)

Arguments

Details

U = \sum_i R_i - \frac{m(m + 1)}{2}

where R_i are the ranks of the first sample x of size m. We compute

\frac{(U - mn(1/2 + \theta))}{\sqrt{mn(m + n + 1) / 12}}

where \theta is the alternative hypothesis shift on the probability scale, i.e. P(X > Y) = 1/2 + \theta.

Value

the standardized Wilcoxon statistic