# Simulating multi-arm multi-stage designs

`mams.sim.Rd`

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

## Arguments

- nsim
Number of simulations (default=

`10000`

).- nMat
Jx(K+1) dimensional matrix of observed/expected sample sizes. Rows correspond to stages and columns to arms. First column is control (default: 2x5 matrix with 44 subjects per stage and arm).

- 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=

`rep(0.5, 4)`

).- 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.

- parallel
if

`TRUE`

(default), allows parallelisation of the computation via a user-defined strategy specified by means of the function`future::plan()`

. If not set differently, the default strategy is`sequential`

, which corresponds to a computation without parallelisation.

## 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 paramterization 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`

.

The 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.

## Value

An object of the class MAMS.sim containing the following components:

`res$prop.rej <- rej/nsim`

- 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.

## 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: doi: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: doi:10.1093/biomet/ass002

## Examples

```
# \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)
#> Simulated error rates based on 10000 simulations
#>
#>
#> Prop. rejecting at least 1 hypothesis: 0.050
#> Prop. rejecting first hypothesis (Z_1>Z_2,...,Z_K) 0.012
#> Prop. rejecting hypothesis 1: 0.014
#> Expected sample size: 342.606
# 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)
#> Simulated error rates based on 10000 simulations
#>
#>
#> Prop. rejecting at least 1 hypothesis: 0.052
#> Prop. rejecting first hypothesis (Z_1>Z_2,...,Z_K) 0.014
#> Prop. rejecting hypothesis 1: 0.017
#> Expected sample size: 342.060
# 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)
#> Simulated error rates based on 10000 simulations
#>
#>
#> Prop. rejecting at least 1 hypothesis: 0.931
#> Prop. rejecting first hypothesis (Z_1>Z_2,...,Z_K) 0.909
#> Prop. rejecting hypotheses 1 or 2: 0.926
#> Expected sample size: 347.534
# 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)
#> Simulated error rates based on 10000 simulations
#>
#>
#> Prop. rejecting at least 1 hypothesis: 0.942
#> Prop. rejecting first hypothesis (Z_1>Z_2,...,Z_K) 0.396
#> Prop. rejecting hypothesis 4: 0.504
#> Expected sample size: 361.033
##
## 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))
)
#> Simulated error rates based on 25000 simulations
#>
#>
#> Prop. rejecting at least 1 hypothesis: 0.927
#> Prop. rejecting first hypothesis (Z_1>Z_2,...,Z_K) 0.905
#> Prop. rejecting hypotheses 1 or 2: 0.921
#> Expected sample size: 346.540
#> user system elapsed
#> 1.18 0.00 2.56
# 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))
)
#> Simulated error rates based on 25000 simulations
#>
#>
#> Prop. rejecting at least 1 hypothesis: 0.927
#> Prop. rejecting first hypothesis (Z_1>Z_2,...,Z_K) 0.905
#> Prop. rejecting hypotheses 1 or 2: 0.921
#> Expected sample size: 346.540
#> user system elapsed
#> 0.83 0.05 2.33
# 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))
)
#> Simulated error rates based on 25000 simulations
#>
#>
#> Prop. rejecting at least 1 hypothesis: 0.927
#> Prop. rejecting first hypothesis (Z_1>Z_2,...,Z_K) 0.905
#> Prop. rejecting hypotheses 1 or 2: 0.921
#> Expected sample size: 346.540
#> user system elapsed
#> 1.40 0.02 4.17
plan("default")
# }
```