Package 'MAMS'

Title:	Designing Multi-Arm Multi-Stage Studies
Description:	Designing multi-arm multi-stage studies with (asymptotically) normal endpoints and known variance.
Authors:	Thomas Jaki [aut, cre] , Dominique-Laurent Couturier [aut] , Dominic Magirr [aut], Nikita Mozgunov [aut] , Philip Pallmann [aut]
Maintainer:	Thomas Jaki <[email protected]>
License:	GPL-2
Version:	3.0.0
Built:	2024-12-19 06:25:39 UTC
Source:	CRAN

Help Index

.onAttach
Function to design multi-arm multi-stage studies with normal endpoints
Simulating multi-arm multi-stage designs
Shows changes and news
Function to update boundaries based on observed sample sizes
Function to design multi-arm multi-stage studies with ordinal or binary endpoints
Plot method for MAMS objects
Plot method for MAMS.stepdown objects
Generic print function for class MAMS.
Generic print function for class MAMS.stepdown.
Function to find stopping boundaries for a 2- or 3-stage (step-down) multiple-comparisons-with-control test.
Update the stopping boundaries of multi-arm multi-stage study at an interim analysis, allowing for unplanned treatment selection and/or sample-size reassessment.
Generic summary function for class MAMS.
Generic summary function for class MAMS.stepdown.
Function to design multi-arm multi-stage studies with time-to-event endpoints

.onAttach

Description

Print MAMS package info

Usage

.onAttach(...)
.onAttach(...)

Arguments

...

Further arguments passed to or from other methods.

Function to design multi-arm multi-stage studies with normal endpoints

Description

The function determines the boundaries of a multi-arm multi-stage study for a given boundary shape and finds the required number of subjects.

Usage

mams(obj = NULL, K=NULL, J=NULL, alpha=NULL, power=NULL, r=NULL, 
                     r0=NULL, p=NULL, p0=NULL, delta=NULL, delta0=NULL, 
                     sd=NULL,ushape=NULL, lshape=NULL, ufix=NULL, lfix=NULL, 
                     nstart=NULL, nstop=NULL, sample.size=NULL, Q=NULL,
                     type=NULL, parallel=NULL, print=NULL, nsim=NULL, 
                     H0=NULL, method=NULL)
mams(obj = NULL, K=NULL, J=NULL, alpha=NULL, power=NULL, r=NULL, 
                     r0=NULL, p=NULL, p0=NULL, delta=NULL, delta0=NULL, 
                     sd=NULL,ushape=NULL, lshape=NULL, ufix=NULL, lfix=NULL, 
                     nstart=NULL, nstop=NULL, sample.size=NULL, Q=NULL,
                     type=NULL, parallel=NULL, print=NULL, nsim=NULL, 
                     H0=NULL, method=NULL)

Arguments

`obj`	object of class `MAMS`
`K`	Number of experimental treatments (default=4).
`J`	Number of stages (default=2).
`alpha`	One-sided familywise error rate (default=0.05).
`power`	Desired power (default=0.9).
`r`	Vector of allocation ratios (default=1:2).
`r0`	Vector ratio on control (default=1:2).
`p`	Interesting treatment effect on the probability scale. See Details (default=0.75).
`p0`	Uninteresting treatment effect on the probability scale. See Details (default=0.5). Note that this parameter affects the sample size estimation to ensure that Treatment 1 is best only when selecting the simultaneous stopping rule (i.e., 'method = "simultaneous"') and, for all methods, as values for treatment arms 2 to K in the simulations under H1.
`delta`	Interesting treatment effect on the traditional scale. See Details (default=NULL).
`delta0`	Uninteresting treatment effect on the traditional scale. See Details (default=NULL). Note that this parameter affects the sample size estimation to ensure that Treatment 1 is best only when selecting the simultaneous stopping rule (i.e., 'method = "simultaneous"') and, for all methods, as values for treatment arms 2 to K in the simulations under H1.
`sd`	Standard deviation, assumed to be known. See Details (default=NULL).
`ushape`	Shape of upper boundary. Either a function specifying the shape or one of "pocock", "obf" (the default), "triangular" and "fixed". See details.
`lshape`	Shape of lower boundary. Either a function specifying the shape or one of "pocock", "obf", "triangular" and "fixed" (the default). See details.
`ufix`	Fixed upper boundary (default=NULL). Only used if shape="fixed".
`lfix`	Fixed lower boundary (default=0). Only used if shape="fixed".
`nstart`	Starting point for finding the sample size (default=1).
`nstop`	Stopping point for finding the sample size (default=NULL).
`sample.size`	Logical if sample size should be found as well (default=TRUE).
`Q`	Number of quadrature points per dimension in the outer integral (default=20).
`type`	Will be changed automatically by the wrappers tite.mams() (to "tite") and ordinal.mams() (to "ordinal") to customise the output.
`parallel`	if TRUE (default), allows parallelization 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 parallelization.
`print`	if TRUE (default), indicate at which stage the computation is.
`nsim`	a scalar indicating the number of simulations (default = 50'000, minimum = 1000)
`H0`	if TRUE (default), the simulation also considers the case with all effect sizes set to 0.
`method`	Type of the desired design: `simultaneous`(default) for simultaneous stopping rules, `sep` for separate stopping, and `dtl` for drop-the-losers design.

Details

This function finds the boundaries and sample size of a multi-arm multi-stage study with K active treatments plus control in which all promising treatments are continued at interim analyses as described in Magirr et al (2012). At each interim analysis the test statistics are compared to the lower (futility) bound and any treatment whose corresponding test statistic falls below that bound is discontinued. Similarly if any test statistic exceeds the upper (efficacy) bound the null hypothesis corresponding to that treatment can be rejected and superiority of that treatment over control claimed. At the same time the study is stopped. If at least one test statistic exceeds the lower bound and none exceeds the upper bound the study is continued and further patients are recruited to all remaining experimental treatments plus control.

The design is found under the least favorable configuration, which requires an interesting treatment effect p that if present we would like to find with high probability and an uninteresting effect p0. Both p and p0 are 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 p=0.5 the experimental treatment and control perform equally well. The advantage of this parameterization is that no knowledge about the variance is required. To convert traditional effect sizes, d $\delta$ to this format use $p=\Phi(\frac{\delta}{\sqrt{2}\sigma})$ . Alternatively, the interesting and uninteresting effect size can also be specified directly on the traditional scale of delta and delta with an additional specification of the standard deviation sd assumed to be known.

The shape of the boundaries (ushape, lshape) are either using the predefined shapes following Pocock (1977), O'Brien & Fleming (1979) or the triangular Test (Whitehead, 1997) using options "⁠pocock"⁠, "obf"or "triangular" respectively, are constant (option "fixed") or supplied in as a function. If a function is passed it should require exactly one argument specifying the number of stages and return a vector of the same length. The lower boundary shape is required to be non-decreasing while the upper boundary shape needs to be non-increasing. If a fixed lower boundary is used, lfix must be smaller than $\Phi^{-1}(1-\alpha)/2$ to ensure that it is smaller than the upper boundary.

The default starting point for finding the sample size is nstart=1, and the default point where the search is stopped (when nstop=NULL) is 3 times the sample size of the corresponding fixed single-stage design.

Computation of designs with more than four stages are very time consuming and not advised. The parameter sample.size controls whether the required sample size is computed as well. Setting to FALSE approximately halves the computation time.

For designs with more than 2 stages, parallelization of the computation by means of the packages future and future.apply lead to decreased computation times when choosing a parallelization strategy like, for example, multicore (using separate forked R processes, available to unix/osx users) or multisession (using separate R sessions, available to all users) (refer to future::plan() for detail).

Value

An object of the class MAMS 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.
`alpha`	Familywise error rate.
`alpha.star`	Cumulative familywise error rate spent by each analysis.
`power`	Power under least favorable configuration.
`rMat`	Matrix of allocation ratios. First row corresponds to control while subsequent rows are for the experimental treatments.
`sim`	a list indicating, for each hypothesis of interest (null and/or alternative), the expected sample size and standard deviation per group (ess), the cumulated probability of efficacy (efficacy) and futility (futility) per treatment arm and look
`input`	the list of all input parameters except K and J

Author(s)

Thomas Jaki, Dominic Magirr, Dominique-Laurent Couturier and Nikita Mozgunov

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

Pocock S.J. (1977), Group sequential methods in the design and analysis of clinical trials, Biometrika, 64(2), 191-199.

O'Brien P.C., and Fleming T.R. (1979), A multiple testing procedure for clinical trials, Biometrics, 35(3), 549-556.

Whitehead J. (1997), The Design and Analysis of Sequential Clinical Trials, Wiley: Chichester, UK. Wason J, Stallard N, Bowden J, Jennison C. A multi-stage drop-the-losers design for multi-arm clinical trials. Statistical Methods in Medical Research. 2017;26(1):508-524. doi:10.1177/0962280214550759

Examples


## A fixed sample (single stage) design specified on the p scale
mams(K=4, J=1, alpha=0.05, power=0.9, r=1, r0=1, p=0.65, p0=0.55)

## The same design specified on the delta scale

mams(K=4, J=1, alpha=0.05, power=0.9, r=1, r0=1, p=NULL, p0=NULL,
     delta=0.545, delta0=0.178, sd=1)

## An example in Table 1 of Magirr et al (2012)
# 2-stage design with O'Brien & Fleming efficacy and zero futility boundary

mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2, p=0.65, p0=0.55,
     ushape="obf", lshape="fixed", lfix=0, nstart=40)

## An example of separate stopping rules
# 2-stage design with O'Brien & Fleming efficacy and zero futility boundary

mams(method = "sep",K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2, 
       p=0.65, p0=0.55, ushape="obf", lshape="fixed", lfix=0, nstart=40)

# An example of running drop-the-losers design 
# `K` should be defined as vector length of J defining allocation arms per 
# stages with final element equal to 1.
mams(method = "dtl", K=c(4,1), J=2, alpha=0.05,  
         power=0.9, r=1:2, r0=1:2, p=0.65, p0=0.55, ushape="obf", 
         lshape="fixed", lfix=0, nstart=40)



# Note that these examples may take a few minutes to run

## 3-stage design with Triangular efficacy and futility boundary
mams(K=4, J=3, alpha=0.05, power=0.9, r=1:3, r0=1:3, p=0.65, p0=0.55,
  ushape="triangular", lshape="triangular", nstart=30)

## Different allocation ratios between control and experimental treatments.
## Twice as many patients are randomized to control at each stage.
  mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=c(2, 4), p=0.65, 
  p0=0.55, ushape="obf", lshape="fixed", lfix=0, nstart=30)


  ##
  ## example considering different parallelization strategies
  ##


  # parallel = FALSE (future framework not used)
  set.seed(1)
  system.time(
  print(mams(K=4, J=3, alpha=0.05, power=0.9, r=1:3, r0=1:3,
          p=0.65, p0=0.55, ushape="triangular", lshape="triangular",
          nstart=30, parallel = FALSE))
          )
 # parallel = TRUE (default) with default strategy (sequential computation)
 plan(sequential)
 set.seed(1)
 system.time(
 print(mams(K=4, J=3, alpha=0.05, power=0.9, r=1:3, r0=1:3,
          p=0.65, p0=0.55, ushape="triangular", lshape="triangular", 
          nstart=30))
          )
 # parallel = TRUE(default) with multisession strategy (parallel computation)
 plan(multisession)
 set.seed(1)
 system.time(
 print(mams(K=4, J=3, alpha=0.05, power=0.9, r=1:3, r0=1:3, 
          p=0.65, p0=0.55, ushape="triangular", lshape="triangular",
           nstart=30))
          )
          plan("default")
          
## A fixed sample (single stage) design specified on the p scale
mams(K=4, J=1, alpha=0.05, power=0.9, r=1, r0=1, p=0.65, p0=0.55)

## The same design specified on the delta scale

mams(K=4, J=1, alpha=0.05, power=0.9, r=1, r0=1, p=NULL, p0=NULL,
     delta=0.545, delta0=0.178, sd=1)

## An example in Table 1 of Magirr et al (2012)
# 2-stage design with O'Brien & Fleming efficacy and zero futility boundary

mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2, p=0.65, p0=0.55,
     ushape="obf", lshape="fixed", lfix=0, nstart=40)

## An example of separate stopping rules
# 2-stage design with O'Brien & Fleming efficacy and zero futility boundary

mams(method = "sep",K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2, 
       p=0.65, p0=0.55, ushape="obf", lshape="fixed", lfix=0, nstart=40)

# An example of running drop-the-losers design 
# `K` should be defined as vector length of J defining allocation arms per 
# stages with final element equal to 1.
mams(method = "dtl", K=c(4,1), J=2, alpha=0.05,  
         power=0.9, r=1:2, r0=1:2, p=0.65, p0=0.55, ushape="obf", 
         lshape="fixed", lfix=0, nstart=40)



# Note that these examples may take a few minutes to run

## 3-stage design with Triangular efficacy and futility boundary
mams(K=4, J=3, alpha=0.05, power=0.9, r=1:3, r0=1:3, p=0.65, p0=0.55,
  ushape="triangular", lshape="triangular", nstart=30)

## Different allocation ratios between control and experimental treatments.
## Twice as many patients are randomized to control at each stage.
  mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=c(2, 4), p=0.65, 
  p0=0.55, ushape="obf", lshape="fixed", lfix=0, nstart=30)


  ##
  ## example considering different parallelization strategies
  ##


  # parallel = FALSE (future framework not used)
  set.seed(1)
  system.time(
  print(mams(K=4, J=3, alpha=0.05, power=0.9, r=1:3, r0=1:3,
          p=0.65, p0=0.55, ushape="triangular", lshape="triangular",
          nstart=30, parallel = FALSE))
          )
 # parallel = TRUE (default) with default strategy (sequential computation)
 plan(sequential)
 set.seed(1)
 system.time(
 print(mams(K=4, J=3, alpha=0.05, power=0.9, r=1:3, r0=1:3,
          p=0.65, p0=0.55, ushape="triangular", lshape="triangular", 
          nstart=30))
          )
 # parallel = TRUE(default) with multisession strategy (parallel computation)
 plan(multisession)
 set.seed(1)
 system.time(
 print(mams(K=4, J=3, alpha=0.05, power=0.9, r=1:3, r0=1:3, 
          p=0.65, p0=0.55, ushape="triangular", lshape="triangular",
           nstart=30))
          )
          plan("default")

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

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

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.

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.

Author(s)

Thomas Jaki, Dominic Magirr and Dominique-Laurent Couturier

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

Examples


# 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")

# 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")

Shows changes and news

Description

Functions showing changes since previous versions.

Usage

MAMSNews()
MAMSNews()

Details

Displays the changes and news given in the NEWS file of the package.

Value

Screen output.

Author(s)

Thomas Jaki

Examples

MAMSNews()
MAMSNews()

Function to update boundaries based on observed sample sizes

Description

The function determines updated boundaries of a multi-arm multi-stage study based on observed number of observations per arm.

Usage

new.bounds(
  K = 3,
  J = 2,
  alpha = 0.05,
  nMat = matrix(c(10, 20), nrow = 2, ncol = 4),
  u = NULL,
  l = NULL,
  ushape = "obf",
  lshape = "fixed",
  ufix = NULL,
  lfix = 0,
  N = 20,
  parallel = TRUE,
  print = TRUE
)
new.bounds(
  K = 3,
  J = 2,
  alpha = 0.05,
  nMat = matrix(c(10, 20), nrow = 2, ncol = 4),
  u = NULL,
  l = NULL,
  ushape = "obf",
  lshape = "fixed",
  ufix = NULL,
  lfix = 0,
  N = 20,
  parallel = TRUE,
  print = TRUE
)

Arguments

`K`	Number of experimental treatments (default=3).
`J`	Number of stages (default=2).
`alpha`	One-sided familywise error rate (default=0.05).
`nMat`	Jx(K+1) dimensional matrix of observed/expected sample sizes. Rows correspond to stages and columns to arms. First column is control (default: 2x4 matrix with 10 subjects per stage and arm).
`u`	Vector of previously used upper boundaries (default=NULL).
`l`	Vector of previously used upper boundaries (default=NULL).
`ushape`	Shape of upper boundary. Either a function specifying the shape or one of "pocock", "obf" (the default), "triangular" and "fixed". See details.
`lshape`	Shape of lower boundary. Either a function specifying the shape or one of "pocock", "obf", "triangular" and "fixed" (the default). See details.
`ufix`	Fixed upper boundary (default=NULL). Only used if shape="fixed".
`lfix`	Fixed lower boundary (default=0). Only used if shape="fixed".
`N`	Number of quadrature points per dimension in the outer integral (default=20).
`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.
`print`	if TRUE (default), indicate at which stage the computation is.

Details

This function finds the boundaries for a given matrix of sample sizes in multi-arm multi-stage study with K active treatments plus control. The vectors u and l are the boundaries used so far while u.shape and l.shape specify the shape to the boundaries for the remaining analysis. By specifying u and l as NULL, a design using only the shapes given by ushape and lshape can be found for any sample sizes per stage and arm.

The shape of the boundaries (ushape, lshape) are either using the predefined shapes following Pocock (1977), O'Brien & Fleming (1979) or the triangular Test (Whitehead, 1997) using options "pocock", "obf" or "triangular" respectively, are constant (option "fixed") or supplied in as a function. If a function is passed it should require exactly one argument specifying the number of stages and return a vector of the same length. The lower boundary shape is required to be non-decreasing while the upper boundary shape needs to be non-increasing. If a fixed lower boundary is used, lfix must be smaller than $\Phi^{-1}(1-\alpha)/2$ to ensure that it is smaller than the upper boundary.

Value

An object of the class MAMS 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.
`alpha`	Familywise error rate.
`power`	Power under least favorable configuration.
`rMat`	Matrix of allocation ratios. First row corresponds to control and second row to experimental treatments.

Author(s)

Thomas Jaki, Dominic Magirr and Dominique-Laurent Couturier

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

Magirr D., Stallard N. and Jaki T. (2014), Flexible sequential designs for multi-arm clinical trials, Statistics in Medicine, 33(19), 3269-3279. Link: doi:10.1002/sim.6183

Pocock S.J. (1977), Group sequential methods in the design and analysis of clinical trials, Biometrika, 64(2), 191-199.

O'Brien P.C., Fleming T.R. (1979), A multiple testing procedure for clinical trials, Biometrics, 35(3), 549-556.

Whitehead J. (1997), The Design and Analysis of Sequential Clinical Trials, Wiley: Chichester, UK.

Examples


# 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. Results are equivalent to using 
 mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2, ushape="obf",
           lshape="fixed", lfix=0, sample.size=FALSE)
new.bounds(K=4, J=2, alpha=0.05, nMat=matrix(c(10, 20), nrow=2, ncol=5),
u=NULL, l=NULL, 
           ushape="obf", lshape="fixed", lfix=0)
# A 2-stage design that was designed to use an O'Brien & Fleming efficacy 
# and zero futility boundary with equal sample size per arm and stage (n=14).
# The observed sample size after stage one are 10, 10, 18, 10, 13 for each 
# arm while the original upper bounds used are (3.068, 2.169) for stage 1. 
# The updated bounds are (3.068, 2.167).
new.bounds(K=4, J=2, alpha=0.05, 
     nMat=matrix(c(10, 28, 10, 28, 18, 28, 10, 28, 13, 28), nrow=2, ncol=5), 
     u=3.068, l=0, ushape="obf", lshape="fixed", lfix=0)
           
# same using parallelisation via separate R sessions running in the 
# background
future::plan(multisession)
new.bounds(K=4, J=2, alpha=0.05, 
           nMat=matrix(c(10, 28, 10, 28, 18, 28, 10, 28, 13, 28), 
           nrow=2, ncol=5), 
           u=3.068, l=0, ushape="obf", lshape="fixed", lfix=0)
future::plan("default")

# 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. Results are equivalent to using 
 mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2, ushape="obf",
           lshape="fixed", lfix=0, sample.size=FALSE)
new.bounds(K=4, J=2, alpha=0.05, nMat=matrix(c(10, 20), nrow=2, ncol=5),
u=NULL, l=NULL, 
           ushape="obf", lshape="fixed", lfix=0)
# A 2-stage design that was designed to use an O'Brien & Fleming efficacy 
# and zero futility boundary with equal sample size per arm and stage (n=14).
# The observed sample size after stage one are 10, 10, 18, 10, 13 for each 
# arm while the original upper bounds used are (3.068, 2.169) for stage 1. 
# The updated bounds are (3.068, 2.167).
new.bounds(K=4, J=2, alpha=0.05, 
     nMat=matrix(c(10, 28, 10, 28, 18, 28, 10, 28, 13, 28), nrow=2, ncol=5), 
     u=3.068, l=0, ushape="obf", lshape="fixed", lfix=0)
           
# same using parallelisation via separate R sessions running in the 
# background
future::plan(multisession)
new.bounds(K=4, J=2, alpha=0.05, 
           nMat=matrix(c(10, 28, 10, 28, 18, 28, 10, 28, 13, 28), 
           nrow=2, ncol=5), 
           u=3.068, l=0, ushape="obf", lshape="fixed", lfix=0)
future::plan("default")

Function to design multi-arm multi-stage studies with ordinal or binary endpoints

Description

The function determines (approximately) the boundaries of a multi-arm multi-stage study with ordinal or binary endpoints for a given boundary shape and finds the required number of subjects.

Usage

ordinal.mams(
  prob = c(0.35, 0.4, 0.25),
  or = 2,
  or0 = 1.2,
  K = 4,
  J = 2,
  alpha = 0.05,
  power = 0.9,
  r = 1:2,
  r0 = 1:2,
  ushape = "obf",
  lshape = "fixed",
  ufix = NULL,
  lfix = 0,
  nstart = 1,
  nstop = NULL,
  sample.size = TRUE,
  Q = 20,
  parallel = TRUE,
  print = TRUE
)
ordinal.mams(
  prob = c(0.35, 0.4, 0.25),
  or = 2,
  or0 = 1.2,
  K = 4,
  J = 2,
  alpha = 0.05,
  power = 0.9,
  r = 1:2,
  r0 = 1:2,
  ushape = "obf",
  lshape = "fixed",
  ufix = NULL,
  lfix = 0,
  nstart = 1,
  nstop = NULL,
  sample.size = TRUE,
  Q = 20,
  parallel = TRUE,
  print = TRUE
)

Arguments

`prob`	Vector of expected probabilities of falling into each category under control conditions. The elements must sum up to one (default=c(0.35, 0.4, 0.25)).
`or`	Interesting treatment effect on the scale of odds ratios (default=2).
`or0`	Uninteresting treatment effect on the scale of odds ratios (default=1.2).
`K`	Number of experimental treatments (default=4).
`J`	Number of stages (default=2).
`alpha`	One-sided familywise error rate (default=0.05).
`power`	Desired power (default=0.9).
`r`	Vector of allocation ratios (default=1:2).
`r0`	Vector ratio on control (default=1:2).
`ushape`	Shape of upper boundary. Either a function specifying the shape or one of "pocock", "obf" (the default), "triangular" and "fixed".
`lshape`	Shape of lower boundary. Either a function specifying the shape or one of "pocock", "obf", "triangular" and "fixed" (the default).
`ufix`	Fixed upper boundary (default=NULL). Only used if shape="fixed".
`lfix`	Fixed lower boundary (default=0). Only used if shape="fixed".
`nstart`	Starting point for finding the sample size (default=1).
`nstop`	Stopping point for finding the sample size (default=NULL).
`sample.size`	Logical if sample size should be found as well (default=TRUE).
`Q`	Number of quadrature points per dimension in the outer integral (default=20).
`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.
`print`	if TRUE (default), indicate at which stage the computation is.

Details

This function finds the (approximate) boundaries and sample size of a multi-arm multi-stage study with ordinal or binary endpoints with K active treatments plus control in which all promising treatments are continued at interim analyses as described in Magirr et al (2012). It is a wrapper around the basic mams function to facilitate its use with ordinal and binary endpoints, following ideas of Whitehead & Jaki (2009) and Jaki & Magirr (2013). For a binary endpoint the vector prob has only two elements (success/failure, yes/no, etc.). See mams for further details on the basic methodology.

Value

An object of the class MAMS containing the following components:

`prob`	Vector of expected probabilities of falling into each category under control conditions. The elements must sum up to one (default=`c(0.35, 0.4, 0.25)`).
`or`	Interesting treatment effect on the scale of odds ratios (default=`2`).
`or0`	Uninteresting treatment effect on the scale of odds ratios (default=`1.2`).
`K`	Number of experimental treatments (default=`4`).
`J`	Number of stages (default=`2`).
`alpha`	One-sided familywise error rate (default=`0.05`).
`power`	Desired power (default=`0.9`).
`r`	Vector of allocation ratios (default=`1:2`).
`r0`	Vector ratio on control (default=`1:2`).
`ushape`	Shape of upper boundary. Either a function specifying the shape or one of `"pocock"`, `"obf"` (the default), `"triangular"` and `"fixed"`.
`lshape`	Shape of lower boundary. Either a function specifying the shape or one of `"pocock"`, `"obf"`, `"triangular"` and `"fixed"` (the default).
`ufix`	Fixed upper boundary (default=`NULL`). Only used if `shape="fixed"`.
`lfix`	Fixed lower boundary (default=`0`). Only used if `shape="fixed"`.
`nstart`	Starting point for finding the sample size (default=`1`).
`nstop`	Stopping point for finding the sample size (default=`NULL`).
`sample.size`	Logical if sample size should be found as well (default=`TRUE`).
`N`	Number of quadrature points per dimension in the outer integral (default=`20`).
`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.
`print`	if `TRUE` (default), indicate at which stage the computation is.

Author(s)

Philip Pallmann

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

Magirr D., Stallard N. and Jaki T. (2014), Flexible sequential designs for multi-arm clinical trials, Statistics in Medicine, 33(19), 3269-3279. Link: doi:10.1002/sim.6183

Pocock S.J. (1977), Group sequential methods in the design and analysis of clinical trials, Biometrika, 64(2), 191-199.

O'Brien P.C., Fleming T.R. (1979), A multiple testing procedure for clinical trials, Biometrics, 35(3), 549-556.

Whitehead J. (1997), The Design and Analysis of Sequential Clinical Trials, Wiley: Chichester, UK.

Examples


## An example based on the example in Whitehead & Jaki (2009)
# 2-stage design with triangular efficacy and futility boundaries
prob <- c(0.075, 0.182, 0.319, 0.243, 0.015, 0.166)
ordinal.mams(prob=prob, or=3.06, or0=1.32, K=3, J=2, alpha=0.05,
                 power=0.9, r=1:2, r0=1:2, ushape="triangular",
                 lshape="triangular")
# same example with parallelisation via separate R sessions running in the
# background
future::plan(multisession)
ordinal.mams(prob=prob, or=3.06, or0=1.32, K=3, J=2, alpha=0.05,
                 power=0.9, r=1:2, r0=1:2, ushape="triangular",
                 lshape="triangular", parallel=TRUE)
future::plan("default")

## An example based on the example in Whitehead & Jaki (2009)
# 2-stage design with triangular efficacy and futility boundaries
prob <- c(0.075, 0.182, 0.319, 0.243, 0.015, 0.166)
ordinal.mams(prob=prob, or=3.06, or0=1.32, K=3, J=2, alpha=0.05,
                 power=0.9, r=1:2, r0=1:2, ushape="triangular",
                 lshape="triangular")
# same example with parallelisation via separate R sessions running in the
# background
future::plan(multisession)
ordinal.mams(prob=prob, or=3.06, or0=1.32, K=3, J=2, alpha=0.05,
                 power=0.9, r=1:2, r0=1:2, ushape="triangular",
                 lshape="triangular", parallel=TRUE)
future::plan("default")

Plot method for MAMS objects

Description

produces as plot of the boundaries.

Usage

## S3 method for class 'MAMS'
plot(
  x,
  ask = TRUE,
  which = 1:2,
  new = TRUE,
  col = NULL,
  pch = NULL,
  lty = NULL,
  main = NULL,
  xlab = "Analysis",
  ylab = "Test statistic",
  ylim = NULL,
  type = NULL,
  las = 1,
  ...
)
## S3 method for class 'MAMS'
plot(
  x,
  ask = TRUE,
  which = 1:2,
  new = TRUE,
  col = NULL,
  pch = NULL,
  lty = NULL,
  main = NULL,
  xlab = "Analysis",
  ylab = "Test statistic",
  ylim = NULL,
  type = NULL,
  las = 1,
  ...
)

Arguments

`x`	An output object of class MAMS
`ask`	A logical indicating if R should wait for the next plot to be displayed.
`which`	A vector indicating which plot(s) to define. `1` displays the efficacy and futility limits per stage, `2` displays the efficacy nd futility probabilities per stage, `1:2` (default) displays both.
`new`	A logical indicating if the new plot of the futility and efficacy limits should be displayed (default='TRUE“).
`col`	A specification for the default plotting color (default=`NULL`). See `par` for more details.
`pch`	Either an integer specifying a symbol or a single character to be used as the default in plotting points (default=`NULL`). See `par` for more details.
`lty`	A specification for the default line type to be used between analyses (default=`NULL`). Setting to zero suppresses plotting of the lines. See `par` for more details.
`main`	An overall title for the plot (default=`NULL`).
`xlab`	A title for the x axis (default=`"Analysis"`).
`ylab`	A title for the y axis (default='"Test statistic"“).
`ylim`	A title for the y axis (default=`"Test statistic"`).
`type`	Type of plot to be used (default=`NULL`). See `plot` for more details.
`las`	A specification of the axis labeling style. The default `1` ensures the labels are always horizontal. See `?par` for details.
`...`	Further arguments passed to or from other methods.

Value

Graphic output.

Author(s)

Thomas Jaki, Dominique-Laurent Couturier

Examples


# 2-stage design with triangular boundaries
res <- mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2,
 p=0.65, p0=0.55, ushape="triangular", lshape="triangular", nstart=30)

plot(res)

# 2-stage design with triangular boundaries
res <- mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2,
 p=0.65, p0=0.55, ushape="triangular", lshape="triangular", nstart=30)

plot(res)

Plot method for MAMS.stepdown objects

Description

produces as plot of the boundaries.

Usage

## S3 method for class 'MAMS.stepdown'
plot(
  x,
  col = NULL,
  pch = NULL,
  lty = NULL,
  main = NULL,
  xlab = "Analysis",
  ylab = "Test statistic",
  ylim = NULL,
  type = NULL,
  bty = "n",
  las = 1,
  ...
)
## S3 method for class 'MAMS.stepdown'
plot(
  x,
  col = NULL,
  pch = NULL,
  lty = NULL,
  main = NULL,
  xlab = "Analysis",
  ylab = "Test statistic",
  ylim = NULL,
  type = NULL,
  bty = "n",
  las = 1,
  ...
)

Arguments

`x`	An output object of class MAMS.stepdown
`col`	A specification for the default plotting color (default=`NULL`). See `par` for more details.
`pch`	Either an integer specifying a symbol or a single character to be used as the default in plotting points (default=`NULL`). See `par` for more details.
`lty`	A specification for the default line type to be used between analyses (default=`NULL`). Setting to zero suppresses plotting of the lines. See `par` for more details.
`main`	An overall title for the plot (default=`NULL`).
`xlab`	A title for the x axis (default=`"Analysis"`).
`ylab`	A title for the y axis (default='"Test statistic"“).
`ylim`	A title for the y axis (default=`"Test statistic"`).
`type`	Type of plot to be used (default=`NULL`). See `plot` for more details.
`bty`	Should a box be drawn around the legend? The default `"n"` does not draw a box, the alternative option `"o"` does.
`las`	A specification of the axis labeling style. The default `1` ensures the labels are always horizontal. See `?par` for details.
`...`	Further arguments passed to or from other methods.

Value

Graphic output.

Author(s)

Thomas Jaki, Dominique-Laurent Couturier

Examples


# 2-stage design with triangular boundaries
res <- mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2,
 p=0.65, p0=0.55, ushape="triangular", lshape="triangular", nstart=30)

plot(res)

# 2-stage design with triangular boundaries
res <- mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2,
 p=0.65, p0=0.55, ushape="triangular", lshape="triangular", nstart=30)

plot(res)

Generic print function for class MAMS.

Description

Generic print function for class MAMS.

Usage

## S3 method for class 'MAMS'
print(x, digits = max(3, getOption("digits") - 4), ...)
## S3 method for class 'MAMS'
print(x, digits = max(3, getOption("digits") - 4), ...)

Arguments

`x`	An output object of class MAMS
`digits`	Number of significant digits to be printed.
`...`	Further arguments passed to or from other methods.

Details

print produces a brief summary of an object from class MAMS including boundaries and requires sample size if initially requested.

Value

Text output.

Author(s)

Thomas Jaki, Dominic Magirr, Philip Pallmann

References

Magirr D, Jaki T, Whitehead J (2012) A generalized Dunnett test for multi-arm multi-stage clinical studies with treatment selection. Biometrika, 99(2), 494-501. Stallard N, Todd S (2003) Sequential designs for phase III clinical trials incorporating treatment selection. Statistics in Medicine, 22(5), 689-703. Magirr D, Stallard N, Jaki T (2014) Flexible sequential designs for multi-arm clinical trials. Statistics in Medicine, 33(19), 3269-3279.

Examples


# 2-stage design with triangular boundaries
res <- mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2, 
             p=0.65,p0=0.55,
             ushape="triangular", lshape="triangular", nstart=30)

print(res)

# 2-stage design with triangular boundaries
res <- mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2, 
             p=0.65,p0=0.55,
             ushape="triangular", lshape="triangular", nstart=30)

print(res)

Generic print function for class MAMS.stepdown.

Description

Generic print function for class MAMS.stepdown.

Usage

## S3 method for class 'MAMS.stepdown'
print(x, digits = max(3, getOption("digits") - 4), ...)
## S3 method for class 'MAMS.stepdown'
print(x, digits = max(3, getOption("digits") - 4), ...)

Arguments

`x`	An output object of class MAMS
`digits`	Number of significant digits to be printed.
`...`	Further arguments passed to or from other methods.

Details

print produces a brief summary of an object from class MAMS.stepdown including boundaries and requires sample size if initially requested.

Value

Text output.

Function to find stopping boundaries for a 2- or 3-stage (step-down) multiple-comparisons-with-control test.

Description

The function determines stopping boundaries for all intersection hypothesis tests in a multi-arm multi-stage study, given the amount of alpha (familywise error rate) to be spent at each analysis.

Usage

stepdown.mams(nMat=matrix(c(10, 20), nrow=2, ncol=4),
             alpha.star=c(0.01, 0.025), lb=0,
             selection="all.promising")
stepdown.mams(nMat=matrix(c(10, 20), nrow=2, ncol=4),
             alpha.star=c(0.01, 0.025), lb=0,
             selection="all.promising")

Arguments

`nMat`	Matrix containing the cumulative sample sizes in each treatment arm columns: control, trt 1, ..., trt K), at each analysis (rows). The number of analyses must be either 2 or 3 (default=matrix(c(10, 20), nrow=2, ncol=4)).
`alpha.star`	Cumulative familywise error rate to be spent at each analysis (default=c(0.01, 0.025)).
`lb`	Fixed lower boundary (default=0).
`selection`	How are treatments selected for the next stage? Using the default "all.promising" method, all treatments with a test statistic exceeding the lower boundary are taken forward to the next stage. If "select.best", only the treatment with the largest statistic may be selected for future stages. (default="all.promising").

Details

The function implements the methods described in Magirr et al (2014) to find individual boundaries for all intersection hypotheses.

Value

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

`l`	Lower boundaries.
`u`	Upper boundaries.
`nMat`	Cumulative sample sizes on each treatment arm.
`K`	Number of experimental treatments.
`J`	Number of stages in the trial.
`alpha.star`	Cumulative familywise error rate spent at each analysis.
`selection`	Pre-specified method of treatment selection.
`zscores`	A list containing the observed test statistics at analyses so far (at the design stage this is NULL).
`selected.trts`	A list containing the treatments selected for each stage.

Author(s)

Dominic Magirr

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

Magirr D., Stallard N. and Jaki T. (2014), Flexible sequential designs for multi-arm clinical trials, Statistics in Medicine, 33(19), 3269-3279. Link: doi:10.1002/sim.6183

Stallard N. and Todd S. (2003), Sequential designs for phase III clinical trials incorporating treatment selection, Statistics in Medicine, 22(5), 689-703.

Examples


# Note that some of these examples may take a few minutes to run
# 2-stage 3-treatments versus control design, all promising treatments
# are selected:
stepdown.mams(nMat=matrix(c(10, 20), nrow=2, ncol=4), 
              alpha.star=c(0.01, 0.05), lb=0, 
              selection="all.promising")
# select the best treatment after the first stage:
stepdown.mams(nMat=matrix(c(10, 20), nrow=2, ncol=4), 
              alpha.star=c(0.01, 0.05), lb=0, 
              selection="select.best")
# 3 stages and unequal randomization:
stepdown.mams(nMat=matrix(c(20, 40, 60, rep(c(10, 20, 30), 3)), 
              nrow=3, ncol=4), 
              alpha.star=c(0.01, 0.025, 0.05), lb=c(0, 0.75), 
              selection="all.promising")

# Note that some of these examples may take a few minutes to run
# 2-stage 3-treatments versus control design, all promising treatments
# are selected:
stepdown.mams(nMat=matrix(c(10, 20), nrow=2, ncol=4), 
              alpha.star=c(0.01, 0.05), lb=0, 
              selection="all.promising")
# select the best treatment after the first stage:
stepdown.mams(nMat=matrix(c(10, 20), nrow=2, ncol=4), 
              alpha.star=c(0.01, 0.05), lb=0, 
              selection="select.best")
# 3 stages and unequal randomization:
stepdown.mams(nMat=matrix(c(20, 40, 60, rep(c(10, 20, 30), 3)), 
              nrow=3, ncol=4), 
              alpha.star=c(0.01, 0.025, 0.05), lb=c(0, 0.75), 
              selection="all.promising")

Update the stopping boundaries of multi-arm multi-stage study at an interim analysis, allowing for unplanned treatment selection and/or sample-size reassessment.

Description

Function to update a planned multi-arm multi-stage design to account for unplanned adaptations.

Usage

stepdown.update(
  current.mams = stepdown.mams(),
  nobs = NULL,
  zscores = NULL,
  selected.trts = NULL,
  nfuture = NULL
)
stepdown.update(
  current.mams = stepdown.mams(),
  nobs = NULL,
  zscores = NULL,
  selected.trts = NULL,
  nfuture = NULL
)

Arguments

`current.mams`	The planned step-down MAMS design prior to the current interim analysis (=defaultstepdown.mams()).
`nobs`	Cumulative sample sizes observed on each treatment arm up to and including the current interim analysis.
`zscores`	Observed vector of test statistics at the current interim analysis.
`selected.trts`	The set of experimental treatments to be taken forward to the next stage of testing. This argument should be omitted at the final analysis.
`nfuture`	A matrix of future cumulative sample sizes. The number of rows must be equal to the originally planned number of stages (2 or 3) minus the number of stages already observed. The number of columns must be equal to the number of treatment arms (default=NULL).

Details

The function implements the ideas described in Magirr et al. (2014) to update a design according to unplanned design modifications. It takes as input the planned multi-arm multi-stage design prior to the interim analysis, together with the actually observed cumulative sample sizes and test statistics. Treatments to be included in future stages, as well as future sample sizes, can be chosen without following pre-specified rules. The output is a new multi-arm multi-stage design for the remaining stages such that the familywise error remains controlled at the pre-specified level.

Author(s)

Dominic Magirr

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

Magirr D., Stallard N. and Jaki T. (2014), Flexible sequential designs for multi-arm clinical trials, Statistics in Medicine, 33(19), 3269-3279. Link: doi:10.1002/sim.6183

Stallard N. and Todd S. (2003), Sequential designs for phase III clinical trials incorporating treatment selection, Statistics in Medicine, 22(5), 689-703.

Examples


# 2-stage 3-treatments versus control design
# all promising treatments are selected:
orig_mams <- stepdown.mams(nMat=matrix(c(10, 20), nrow=2, ncol=4), 
                           alpha.star=c(0.01, 0.05), lb=0, 
                           selection="all.promising")

# make adjustment for the observed sample sizes 
# not being exactly as planned:
stepdown.update(orig_mams, nobs=c(9, 8, 13, 11), 
                 zscores=c(1.1, -0.5, 0.2), 
                 selected.trts=1:3, nfuture=NULL)

# make adjustment for the observed sample sizes 
# not being exactly as planned. In addition, drop treatment 2:
stepdown.update(orig_mams, nobs=c(9, 8, 13, 11), 
                 zscores=c(1.1, -0.5, 0.2), 
                 selected.trts=c(1, 3), nfuture=NULL)

# make adjustment for the observed sample sizes not being 
# exactly as planned. In addition, drop treatment 2. In addition, 
# double the planed cumulative second stage sample sizes:
updated_mams <- stepdown.update(orig_mams, nobs=c(9, 8, 13, 11), 
                                 zscores=c(1.1, -0.5, 0.2), 
                                 selected.trts=c(1, 3), 
                                 nfuture=matrix(c(40, 40, 13, 40), 
                                 nrow=1, ncol=4))

# Account for the observed second stage sample sizes:
stepdown.update(updated_mams, nobs=c(38, 41, 13, 36), 
                zscores=c(1.9, -Inf, 1.2), 
                selected.trts=NULL)

# 'select.best' design. Account for actually observed sample sizes 
# in first stage, and drop treatment 2:
orig_mams <- stepdown.mams(nMat=matrix(c(10, 20), nrow=2, ncol=4), 
                           alpha.star=c(0.01, 0.05), lb=0, 
                           selection="select.best")

stepdown.update(orig_mams, nobs=c(9, 8, 13, 11), 
                 zscores=c(1.1, -0.5, 0.2), 
                 selected.trts=c(1, 3), nfuture=NULL)

# 2-stage 3-treatments versus control design
# all promising treatments are selected:
orig_mams <- stepdown.mams(nMat=matrix(c(10, 20), nrow=2, ncol=4), 
                           alpha.star=c(0.01, 0.05), lb=0, 
                           selection="all.promising")

# make adjustment for the observed sample sizes 
# not being exactly as planned:
stepdown.update(orig_mams, nobs=c(9, 8, 13, 11), 
                 zscores=c(1.1, -0.5, 0.2), 
                 selected.trts=1:3, nfuture=NULL)

# make adjustment for the observed sample sizes 
# not being exactly as planned. In addition, drop treatment 2:
stepdown.update(orig_mams, nobs=c(9, 8, 13, 11), 
                 zscores=c(1.1, -0.5, 0.2), 
                 selected.trts=c(1, 3), nfuture=NULL)

# make adjustment for the observed sample sizes not being 
# exactly as planned. In addition, drop treatment 2. In addition, 
# double the planed cumulative second stage sample sizes:
updated_mams <- stepdown.update(orig_mams, nobs=c(9, 8, 13, 11), 
                                 zscores=c(1.1, -0.5, 0.2), 
                                 selected.trts=c(1, 3), 
                                 nfuture=matrix(c(40, 40, 13, 40), 
                                 nrow=1, ncol=4))

# Account for the observed second stage sample sizes:
stepdown.update(updated_mams, nobs=c(38, 41, 13, 36), 
                zscores=c(1.9, -Inf, 1.2), 
                selected.trts=NULL)

# 'select.best' design. Account for actually observed sample sizes 
# in first stage, and drop treatment 2:
orig_mams <- stepdown.mams(nMat=matrix(c(10, 20), nrow=2, ncol=4), 
                           alpha.star=c(0.01, 0.05), lb=0, 
                           selection="select.best")

stepdown.update(orig_mams, nobs=c(9, 8, 13, 11), 
                 zscores=c(1.1, -0.5, 0.2), 
                 selected.trts=c(1, 3), nfuture=NULL)

Generic summary function for class MAMS.

Description

Produces a detailed summary of an object from class MAMS

Usage

## S3 method for class 'MAMS'
summary(
  object,
  digits = max(3, getOption("digits") - 4),
  extended = FALSE,
  ...
)
## S3 method for class 'MAMS'
summary(
  object,
  digits = max(3, getOption("digits") - 4),
  extended = FALSE,
  ...
)

Arguments

`object`	An output object of class MAMS
`digits`	Number of significant digits to be printed.
`extended`	TRUE or FALSE
`...`	Further arguments passed to or from other methods.

Value

Text output.

Author(s)

Dominique-Laurent Couturier

Examples


# 2-stage design with triangular boundaries
res <- mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2,
             p=0.65, p0=0.55,
             ushape="triangular", lshape="triangular", nstart=30)

summary(res)

# 2-stage design with triangular boundaries
res <- mams(K=4, J=2, alpha=0.05, power=0.9, r=1:2, r0=1:2,
             p=0.65, p0=0.55,
             ushape="triangular", lshape="triangular", nstart=30)

summary(res)

Generic summary function for class MAMS.stepdown.

Description

Generic summary function for class MAMS.stepdown.

Usage

## S3 method for class 'MAMS.stepdown'
summary(object, digits = max(3, getOption("digits") - 4), ...)
## S3 method for class 'MAMS.stepdown'
summary(object, digits = max(3, getOption("digits") - 4), ...)

Arguments

`object`	An output object of class MAMS
`digits`	Number of significant digits to be printed.
`...`	Further arguments passed to or from other methods.

Details

print produces a brief summary of an object from class MAMS.stepdown including boundaries and requires sample size if initially requested.

Value

Text output.

Function to design multi-arm multi-stage studies with time-to-event endpoints

Description

The function determines (approximately) the boundaries of a multi-arm multi-stage study with time-to-event endpoints for a given boundary shape and finds the required number of events.

Usage

tite.mams(
  hr = 1.5,
  hr0 = 1.1,
  K = 4,
  J = 2,
  alpha = 0.05,
  power = 0.9,
  r = 1:2,
  r0 = 1:2,
  ushape = "obf",
  lshape = "fixed",
  ufix = NULL,
  lfix = 0,
  nstart = 1,
  nstop = NULL,
  sample.size = TRUE,
  Q = 20,
  parallel = TRUE,
  print = TRUE
)
tite.mams(
  hr = 1.5,
  hr0 = 1.1,
  K = 4,
  J = 2,
  alpha = 0.05,
  power = 0.9,
  r = 1:2,
  r0 = 1:2,
  ushape = "obf",
  lshape = "fixed",
  ufix = NULL,
  lfix = 0,
  nstart = 1,
  nstop = NULL,
  sample.size = TRUE,
  Q = 20,
  parallel = TRUE,
  print = TRUE
)

Arguments

`hr`	Interesting treatment effect on the scale of hazard ratios (default=2).
`hr0`	Uninteresting treatment effect on the scale of hazard ratios (default=1.2).
`K`	Number of experimental treatments (default=4).
`J`	Number of stages (default=2).
`alpha`	One-sided familywise error rate (default=0.05).
`power`	Desired power (default=0.9).
`r`	Vector of allocation ratios (default=1:2).
`r0`	Vector ratio on control (default=1:2).
`ushape`	Shape of upper boundary. Either a function specifying the shape or one of "pocock", "obf" (the default), "triangular" and "fixed".
`lshape`	Shape of lower boundary. Either a function specifying the shape or one of "pocock", "obf", "triangular" and "fixed" (the default).
`ufix`	Fixed upper boundary (default=NULL). Only used if shape="fixed".
`lfix`	Fixed lower boundary (default=0). Only used if shape="fixed".
`nstart`	Starting point for finding the sample size (default=1).
`nstop`	Stopping point for finding the sample size (default=NULL).
`sample.size`	Logical if sample size should be found as well (default=TRUE).
`Q`	Number of quadrature points per dimension in the outer integral (default=20).
`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.
`print`	if TRUE (default), indicate at which stage the computation is.

Details

This function finds the (approximate) boundaries and sample size of a multi-arm multi-stage study with time-to-event endpoints with K active treatments plus control in which all promising treatments are continued at interim analyses as described in Magirr et al (2012). It is a wrapper around the basic mams function to facilitate its use with time-to-event endpoints, following ideas of Jaki & Magirr (2013). Note that the sample size is calculated as the required number of events, from which the total sample size can be estimated (e.g., Whitehead 2001). See ?mams for further details on the basic methodology.

Value

An object of the class MAMS 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.
`alpha`	Familywise error rate.
`alpha.star`	Cumulative familywise error rate spent by each analysis.
`power`	Power under least favorable configuration.
`rMat`	Matrix of allocation ratios. First row corresponds to control while subsequent rows are for the experimental treatments.

Author(s)

Philip Pallmann, Dominic Magirr

Examples


## An example 2-stage design with triangular efficacy and futility boundaries
tite.mams(hr=2, hr0=1.5, K=3, J=2, alpha=0.05, power=0.9,
          r=1:2, r0=1:2, ushape="triangular", lshape="triangular")

## An example 2-stage design with triangular efficacy and futility boundaries
tite.mams(hr=2, hr0=1.5, K=3, J=2, alpha=0.05, power=0.9,
          r=1:2, r0=1:2, ushape="triangular", lshape="triangular")

Package 'MAMS'

Help Index

.onAttach

Description

Usage

Arguments

Function to design multi-arm multi-stage studies with normal endpoints

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Simulating multi-arm multi-stage designs

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Shows changes and news

Description

Usage

Details

Value

Author(s)

Examples

Function to update boundaries based on observed sample sizes

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Function to design multi-arm multi-stage studies with ordinal or binary endpoints

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Plot method for MAMS objects

Description

Usage

Arguments

Value

Author(s)

Examples

Plot method for MAMS.stepdown objects

Description

Usage

Arguments

Value

Author(s)

Examples

Generic print function for class MAMS.

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Generic print function for class MAMS.stepdown.

Description

Usage

Arguments

Details