% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/RcppExports.R
\name{getDesign_mams}
\alias{getDesign_mams}
\title{Power and Sample Size for Multi-Arm Multi-Stage Design}
\usage{
getDesign_mams(
  beta = NA_real_,
  IMax = NA_real_,
  theta = NA_real_,
  M = NA_integer_,
  r = 1,
  corr_known = TRUE,
  kMax = 1L,
  informationRates = NA_real_,
  efficacyStopping = NA_integer_,
  futilityStopping = NA_integer_,
  criticalValues = NULL,
  alpha = 0.025,
  typeAlphaSpending = "sfOF",
  parameterAlphaSpending = NA_real_,
  userAlphaSpending = NA_real_,
  futilityBounds = NULL,
  futilityCP = NULL,
  futilityTheta = NULL,
  typeBetaSpending = "none",
  parameterBetaSpending = NA_real_,
  userBetaSpending = NA_real_,
  spendingTime = NA_real_
)
}
\arguments{
\item{beta}{Type II error rate. Provide either \code{beta} or \code{IMax};
the other should be missing.}

\item{IMax}{Maximum information for any active arm versus the common
control. Provide either \code{IMax} or \code{beta}; the other should
be missing.}

\item{theta}{A vector of length \eqn{M} representing the true treatment
effects for each active arm versus the common control. The global null
is \eqn{\theta_i = 0} for all \eqn{i}, and alternatives are one-sided:
\eqn{\theta_i > 0} for at least one \eqn{i = 1, \ldots, M}.}

\item{M}{Number of active treatment arms.}

\item{r}{Randomization ratio of each active arm to the common control.}

\item{corr_known}{Logical. If \code{TRUE}, the correlation between Wald
statistics is derived from the randomization ratio \eqn{r}
as \eqn{r / (r + 1)}. If \code{FALSE}, a conservative correlation of
0 is used.}

\item{kMax}{Number of sequential looks.}

\item{informationRates}{A numeric vector of information rates fixed
before the trial. If unspecified, defaults to \eqn{(1:kMax) / kMax}.}

\item{efficacyStopping}{Indicators of whether efficacy stopping is allowed
at each stage. Defaults to \code{TRUE} if left unspecified.}

\item{futilityStopping}{Indicators of whether futility stopping is allowed
at each stage. Defaults to \code{TRUE} if left unspecified.}

\item{criticalValues}{The matrix of by-level upper boundaries on the
max z-test statistic scale for efficacy stopping.
The first column is for level \code{M}, the second column is for
level \code{M - 1}, and so on, with the last column for level 1.
If left unspecified, the critical values will be computed based
on the specified alpha spending function.}

\item{alpha}{The significance level. Defaults to 0.025.}

\item{typeAlphaSpending}{The type of alpha spending. One of the following:
\code{"OF"} for O'Brien-Fleming boundaries,
\code{"P"} for Pocock boundaries,
\code{"WT"} for Wang & Tsiatis boundaries,
\code{"sfOF"} for O'Brien-Fleming type spending function,
\code{"sfP"} for Pocock type spending function,
\code{"sfKD"} for Kim & DeMets spending function,
\code{"sfHSD"} for Hwang, Shi & DeCani spending function,
\code{"user"} for user defined spending, and
\code{"none"} for no early efficacy stopping.
Defaults to \code{"sfOF"}.}

\item{parameterAlphaSpending}{The parameter value for the alpha spending.
Corresponds to \eqn{\Delta} for \code{"WT"}, \eqn{\rho} for \code{"sfKD"},
and \eqn{\gamma} for \code{"sfHSD"}.}

\item{userAlphaSpending}{The user defined alpha spending. Cumulative alpha
spent up to each stage.}

\item{futilityBounds}{A numeric vector of length \code{kMax - 1}
specifying the futility boundaries on the max z-test statistic scale
for futility stopping.}

\item{futilityCP}{A numeric vector of length \code{kMax - 1} specifying
the futility boundaries on the conditional power scale for futility
stopping.}

\item{futilityTheta}{A numeric vector of length \code{kMax - 1} specifying
the futility boundaries on the parameter scale for futility stopping.}

\item{typeBetaSpending}{The type of beta spending. One of the following:
\code{"sfOF"} for O'Brien-Fleming type spending function,
\code{"sfP"} for Pocock type spending function,
\code{"sfKD"} for Kim & DeMets spending function,
\code{"sfHSD"} for Hwang, Shi & DeCani spending function,
\code{"user"} for user defined spending, and
\code{"none"} for no early futility stopping.
Defaults to \code{"none"}.}

\item{parameterBetaSpending}{The parameter value for the beta spending.
Corresponds to \eqn{\rho} for \code{"sfKD"}, and
\eqn{\gamma} for \code{"sfHSD"}.}

\item{userBetaSpending}{The user defined beta spending. Cumulative beta
spent up to each stage.}

\item{spendingTime}{A numeric vector of length \code{kMax} specifying the
error spending time at each analysis. Values must be strictly increasing
and ends at 1. If omitted, defaults to \code{informationRates}.}
}
\value{
An S3 object of class \code{mams} with the following components:
\itemize{
\item \code{overallResults}: A data frame containing:
\itemize{
\item \code{overallReject}: Overall probability of rejecting the global
null hypothesis.
\item \code{alpha}: Overall significance level.
\item \code{attainedAlpha}: The attained significance level, which is
different from the overall significance level in the presence of
futility stopping.
\item \code{M}: Number of active arms.
\item \code{r}: Randomization ratio per active arm versus control.
\item \code{corr_known}: Whether the correlation among Wald statistics
was assumed known.
\item \code{kMax}: Number of stages.
\item \code{information}: Maximum information for any active arm versus
control.
\item \code{expectedInformationH1}: The expected information under H1.
\item \code{expectedInformationH0}: The expected information under H0.
}
\item \code{byStageResults}: A data frame containing:
\itemize{
\item \code{informationRates}: Information rates at each analysis.
\item \code{efficacyBounds}: Efficacy boundaries on the max Z-scale.
\item \code{futilityBounds}: Futility boundaries on the max Z-scale.
\item \code{rejectPerStage}: Probability of efficacy stopping at each stage.
\item \code{futilityPerStage}: Probability of futility stopping at each stage.
\item \code{cumulativeRejection}: Cumulative probability of efficacy stopping.
\item \code{cumulativeFutility}: Cumulative probability of futility stopping.
\item \code{cumulativeAlphaSpent}: Cumulative alpha spent.
\item \code{efficacyTheta}: Efficacy boundaries on the parameter scale.
\item \code{futilityTheta}: Futility boundaries on the parameter scale.
\item \code{efficacyP}: Efficacy boundaries on the p-value scale.
\item \code{futilityP}: Futility boundaries on the p-value scale.
\item \code{information}: Cumulative information for any active arm versus
control at each analysis.
\item \code{efficacyStopping}: Indicator of whether efficacy stopping
is permitted at each stage.
\item \code{futilityStopping}: Indicator of whether futility stopping
is permitted at each stage.
\item \code{rejectPerStageH0}: The probability for efficacy stopping
under H0.
\item \code{futilityPerStageH0}: The probability for futility stopping
under H0.
\item \code{cumulativeRejectionH0}: The cumulative probability for
efficacy stopping under H0.
\item \code{cumulativeFutilityH0}: The cumulative probability for
futility stopping under H0.
}
\item \code{settings}: A list of input settings:
\itemize{
\item \code{typeAlphaSpending}: The type of alpha spending.
\item \code{parameterAlphaSpending}: The parameter value for the chosen
alpha spending function.
\item \code{userAlphaSpending}: The user-specified alpha spending values.
\item \code{typeBetaSpending}: The type of beta spending.
\item \code{parameterBetaSpending}: The parameter value for the chosen
beta spending function.
\item \code{userBetaSpending}: The user-specified beta spending values.
\item \code{spendingTime}: The error-spending time at each analysis.
}
\item \code{byLevelBounds}: A data frame containing the efficacy boundaries
for each level of testing (i.e., number of active arms remaining) and
each stage. Columns include:
\itemize{
\item \code{level}: Number of active arms remaining (1 to \eqn{M}).
\item \code{stage}: Stage index (1 to \code{kMax}).
\item \code{efficacyBounds}: Efficacy boundaries on the max Z-scale
for the given level and stage.
}
}
}
\description{
Computes either the maximum information and stopping
boundaries for a multi-arm multi-stage design, or
the achieved power when the maximum information and stopping boundaries
are provided.
}
\details{
If \code{corr_known} is \code{FALSE}, critical boundaries are
computed assuming independence among the Wald statistics in each stage
(a conservative assumption). Power calculations, however, use the
correlation implied by the randomization ratio \eqn{r}.
}
\examples{

# Example 1: obtain the maximum information given power
(design1 <- getDesign_mams(
  beta = 0.1, theta = c(0.3, 0.5), M = 2, r = 1.0,
  kMax = 3, informationRates = seq(1, 3)/3,
  alpha = 0.025, typeAlphaSpending = "OF"))

# Example 2: obtain power given the maximum information
(design2 <- getDesign_mams(
  IMax = 110/(2*1^2), theta = c(0.3, 0.5), M = 2, r = 1.0,
  kMax = 3, informationRates = seq(1, 3)/3,
  alpha = 0.025, typeAlphaSpending = "OF"))

# Example 3: derive futility boundaries using beta spending
(design3 <- getDesign_mams(
  beta = 0.1, theta = c(-log(0.5), -log(0.75)),
  M = 2, r = 1.0, corr_known = FALSE,
  kMax = 3, informationRates = seq(1, 3)/3,
  alpha = 0.025, typeAlphaSpending = "sfOF",
  typeBetaSpending = "sfHSD", parameterBetaSpending = -2))

}
\references{
Ping Gao, Yingqiu Li.
Adaptive multiple comparison sequential design (AMCSD) for clinical trials.
Journal of Biopharmaceutical Statistics, 2024, 34(3), 424-440.
}
\author{
Kaifeng Lu, \email{kaifenglu@gmail.com}
}
