mams.sim: Simulating multi-arm multi-stage designs

Description

The function simulates multi-arm multi-stage designs and estimates power and expected sample size.

Usage

mams.sim(obj=NULL,nsim=NULL, nMat=NULL,
u=NULL, l=NULL, pv=NULL, deltav=NULL, sd=NULL, ptest=NULL,
parallel=NULL, H0=NULL, K = NULL)

Value

An object containing the following components:

l: Lower boundary.
u: Upper boundary.
n: Sample size on control in stage 1.
N: Maximum total sample size.
K: Number of experimental treatments.
J: Number of stages in the trial.
rMat: Matrix of allocation ratios. First row corresponds to control and second row to experimental treatments.
nsim: Number of simulation runs.
typeI: The proportion any hypothesis is rejected.
power: The proportion the first hypothesis is rejected and the corresponding test statistic is largest.
ptest: The vector ptest.
prop.rej: The proportion of times at least one of the hypothesis specified by ptest is rejected.
exss: The expected sample size.

Arguments

obj: an object of class MAMS. The parameters/design of the considered in the output of the mams() function are considered as reference for the simulation. If other parameters are given, their values override the parameters of the MAMS object
nsim: Number of simulations (default=`50000``).
nMat: Jx(K+1) dimensional matrix of observed/expected sample sizes. Rows correspond to stages and columns to arms. First column is control (default: NULL).
u: Vector of previously used upper boundaries (default=NULL).
l: Vector of previously used upper boundaries (default=NULL).
pv: Vector of size K of true treatment effects on the probability scale. See Details (default=NULL).
deltav: Vector of size K of true treatment effects on the traditional scale. See Details (default=NULL).
sd: Standard deviation. See Details (default=NULL).
ptest: Vector of treatment numbers for determining power. For example, c(1, 2) will count rejections of one or both hypotheses for testing treatments 1 and 2 against control (default=1).
parallel: if TRUE (default), allows parallelization of the computation via a user-defined strategy specified by means of the function plan. If not set differently, the default strategy is sequential, which corresponds to a computation without parallelization.
H0: if TRUE (default), the simulation also considers the case with all effect sizes set to 0.
K: Allocation for treatment arms (used only with method = "dtl")

Author

Thomas Jaki, Dominic Magirr and Dominique-Laurent Couturier

Details

This function simulates multi-arm multi-stage studies for a given matrix of sample sizes and boundaries given by the vectors u and l. The effect difference between each experimental treatment and control is given by pv and is parameterized as \(P(X_k > X_0 ) = p\). That is the probability of a randomly selected person on treatment k observing a better outcome than a random person on control. For pv=rep(0.5,4) the experimental treatments and control perform equally well (i.e. the global null hypothesis is true). The advantage of this parameterization is that no knowledge about the variance is required. To convert traditional effect sizes, \(\delta\) to this format use \(p=\Phi(\frac{\delta}{\sqrt{2}\sigma})\). Alternatively, the effect size can also be specified directly on the traditional scale of deltav with an additional specification of the standard deviation sd.

he function returns the probability of rejecting any hypothesis (typeI), the power to reject the first hypothesis when the first treatment has the largest estimated effect, the proportion of rejections of the hypothesis specified by ptest (prop.rej) as well as the expected sample size.

References

Jaki T., Pallmann P., and Magirr D. (2019), The R Package MAMS for Designing Multi-Arm Multi-Stage Clinical Trials, Journal of Statistical Software, 88(4), 1-25. Link: tools:::Rd_expr_doi("https://doi.org/10.18637/jss.v088.i04")

Magirr D., Jaki T., and Whitehead J. (2012), A generalized Dunnett test for multi-arm multi-stage clinical studies with treatment selection, Biometrika, 99(2), 494-501. Link: tools:::Rd_expr_doi("https://doi.org/10.1093/biomet/ass002")

Examples

Run this code

# \donttest{
# Note that some of these examples may take a few minutes to run

# 2-stage design with O'Brien & Fleming efficacy and zero futility boundary
# with equal sample size per arm and stage. Design can be found using
# mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2, ushape="obf", 
     # lshape="fixed",
     # lfix=0, p=0.65, p0=0.55)

# under global null hypothesis (using the pv scale)
mams.sim(nsim=10000, nMat=matrix(c(44, 88), nrow=2, ncol=5), 
             u=c(3.068, 2.169),
             l=c(0.000, 2.169), pv=rep(0.5, 4), ptest=1)

# under global null hypothesis (using the deltav scale)
mams.sim(nsim=10000, nMat=matrix(c(44, 88), nrow=2, ncol=5), 
        u=c(3.068, 2.169),
        l=c(0.000, 2.169), pv=NULL, deltav=rep(0, 4), sd=1, ptest=1)

# under LFC
mams.sim(nsim=10000, nMat=matrix(c(44, 88), nrow=2, ncol=5), 
        u=c(3.068, 2.169),
        l=c(0.000, 2.169), pv=c(0.65, 0.55, 0.55, 0.55), ptest=1:2)

# when all treatments doing similarly well
mams.sim(nsim=10000, nMat=matrix(c(44, 88), nrow=2, ncol=5),
        u=c(3.068, 2.169),
        l=c(0.000, 2.169), pv=c(0.63, 0.62, 0.60, 0.61), ptest=4)

##
## example considering different parallelisation strategies
##

# parallel = FALSE (future framework not used)
set.seed(1)
system.time(
 print(mams.sim(nsim=25000, nMat=matrix(c(44, 88), nrow=2, ncol=5), 
                u=c(3.068, 2.169),
                l=c(0.000, 2.169), pv=c(0.65, 0.55, 0.55, 0.55),
                ptest=1:2, parallel=FALSE))
)
# parallel = TRUE (default) with default strategy (sequential computation)
plan(sequential)
set.seed(1)
system.time(
 print(mams.sim(nsim=25000, nMat=matrix(c(44, 88), nrow=2, ncol=5), 
                u=c(3.068, 2.169),
                l=c(0.000, 2.169), pv=c(0.65, 0.55, 0.55, 0.55), ptest=1:2))
)
# parallel = TRUE (default) with multisession strategy (parallel computation)
plan(multisession)
set.seed(1)
system.time(
 print(mams.sim(nsim=25000, nMat=matrix(c(44, 88), nrow=2, ncol=5),
                u=c(3.068, 2.169),
                l=c(0.000, 2.169), pv=c(0.65, 0.55, 0.55, 0.55), ptest=1:2))
)
plan("default")
# }

Run the code above in your browser using DataLab