% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/RcppExports.R
\name{adaptDesign_mams}
\alias{adaptDesign_mams}
\title{Adaptive Multi-Arm Multi-Stage Design}
\usage{
adaptDesign_mams(
  betaNew = NA_real_,
  INew = NA_real_,
  M = NA_integer_,
  r = 1,
  corr_known = TRUE,
  L = NA_integer_,
  zL = NA_real_,
  theta = NA_real_,
  IMax = NA_real_,
  kMax = NA_integer_,
  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,
  spendingTime = NA_real_,
  MullerSchafer = FALSE,
  MNew = NA_integer_,
  selected = NA_integer_,
  rNew = 1,
  kNew = NA_integer_,
  informationRatesNew = NA_real_,
  efficacyStoppingNew = NA_integer_,
  futilityStoppingNew = NA_integer_,
  typeAlphaSpendingNew = "sfOF",
  parameterAlphaSpendingNew = NA_real_,
  futilityBoundsInt = NULL,
  futilityCPInt = NULL,
  futilityThetaInt = NULL,
  typeBetaSpendingNew = "none",
  parameterBetaSpendingNew = NA_real_,
  userBetaSpendingNew = NA_real_,
  spendingTimeNew = NA_real_
)
}
\arguments{
\item{betaNew}{The type II error for the secondary trial.}

\item{INew}{The maximum information for any active arm versus the common
control in the secondary trial. Either
\code{betaNew} or \code{INew} should be provided, while the other
must be missing.}

\item{M}{Number of active treatment arms in the primary trial.}

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

\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 assumed.}

\item{L}{The interim adaptation look of the primary trial.}

\item{zL}{The z-test statistics at the interim adaptation look of
the primary trial.}

\item{theta}{A vector of length \eqn{M} representing the assumed 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{IMax}{Maximum information for any active arm versus the common
control for the primary trial. Must be provided.}

\item{kMax}{The maximum number of stages of the primary trial.}

\item{informationRates}{The information rates of the primary trial.}

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

\item{futilityStopping}{Indicators of whether futility stopping is
allowed at each stage of the primary trial.}

\item{criticalValues}{The matrix of by-level upper boundaries on the
max z-test statistic scale for efficacy stopping for the primary trial.
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 of the primary trial.
Defaults to 0.025.}

\item{typeAlphaSpending}{The type of alpha spending for the primary
trial. 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 of alpha spending
for the primary trial. 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 for the
primary trial. Represents the cumulative alpha spent up to each stage.}

\item{futilityBounds}{The futility boundaries on the max-z statistic
scale for the primary trial. Defaults to \code{rep(-8, kMax-1)}
if left unspecified.}

\item{futilityCP}{The conditional power-based futility bounds for the
primary trial.}

\item{futilityTheta}{The parameter value-based futility bounds for the
primary trial.}

\item{spendingTime}{The error spending time of the primary trial.
Defaults to missing, in which case it is assumed to be the same as
\code{informationRates}.}

\item{MullerSchafer}{Whether to use the Muller and Schafer (2001) method
for trial adaptation.}

\item{MNew}{Number of active treatment arms in the secondary trial.}

\item{selected}{The indices of the selected active treatment arms for
the secondary trial.}

\item{rNew}{Randomization ratio of each active arm to the common control
in the secondary trial.}

\item{kNew}{The number of looks of the secondary trial.}

\item{informationRatesNew}{The spacing of looks of the secondary trial.}

\item{efficacyStoppingNew}{The indicators of whether efficacy stopping is
allowed at each look of the secondary trial. Defaults to \code{TRUE}
if left unspecified.}

\item{futilityStoppingNew}{The indicators of whether futility stopping is
allowed at each look of the secondary trial. Defaults to \code{TRUE}
if left unspecified.}

\item{typeAlphaSpendingNew}{The type of alpha spending for the secondary
trial. One of the following:
\code{"OF"} for O'Brien-Fleming 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, and
\code{"none"} for no early efficacy stopping.
Defaults to \code{"sfOF"}.}

\item{parameterAlphaSpendingNew}{The parameter value of alpha spending
for the secondary trial. Corresponds to
\eqn{\rho} for \code{"sfKD"}, and \eqn{\gamma} for \code{"sfHSD"}.}

\item{futilityBoundsInt}{The futility boundaries on the max-z statistic
scale for new stages of the integrated trial.}

\item{futilityCPInt}{The conditional power-based futility bounds for
new stages of the integrated trial.}

\item{futilityThetaInt}{The parameter value-based futility bounds for the
new stages of the integrated trial.}

\item{typeBetaSpendingNew}{The type of beta spending for the secondary
trial. 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{parameterBetaSpendingNew}{The parameter value of beta spending
for the secondary trial. Corresponds to \eqn{\rho} for \code{"sfKD"},
and \eqn{\gamma} for \code{"sfHSD"}.}

\item{userBetaSpendingNew}{The user-defined cumulative beta spending.
Represents the cumulative beta spent up to each stage of the
secondary trial.}

\item{spendingTimeNew}{The error spending time of the secondary trial.
Defaults to missing, in which case it is assumed to be the same as
\code{informationRatesNew}.}
}
\value{
An \code{adaptDesign_mams} object with three list components:
\itemize{
\item \code{primaryTrial}: A list of selected information for the primary
trial, including \code{M}, \code{r}, \code{corr_known}, \code{L},
\code{zL}, \code{theta}, \code{maxInformation}, \code{kMax},
\code{informationRates}, \code{efficacyBounds}, \code{futilityBounds},
\code{information}, \code{alpha}, \code{conditionalAlpha},
\code{conditionalPower}, \code{MullerSchafer}, and \code{byLevelBounds},
where \code{byLevelBounds} is a data frame with columns \code{level},
\code{stage}, and \code{efficacyBounds}, representing the efficacy
bounds for each combination of the number of active arms and
the stage of analysis in the primary trial.
\item \code{secondaryTrial}: A list of selected information for the secondary
trial, including \code{overallReject}, \code{alpha}, \code{M}, \code{r},
\code{selected}, \code{corr_known}, \code{kMax}, \code{maxInformation},
\code{informationRates}, \code{cumulativeRejection},
\code{cumulativeAlphaSpent}, \code{information},
\code{typeAlphaSpending}, \code{parameterAlphaSpending},
\code{typeBetaSpending}, \code{parameterBetaSpending},
\code{userBetaSpending}, \code{spendingTime}, and
\code{byHypothesisBounds}, where \code{byHypothesisBounds} is a
data frame with columns \code{hypothesis}, \code{stage},
\code{efficacyBounds}, and \code{futilityBounds}, representing
the efficacy and futility bounds for each hypothesis and each
stage of analysis in the secondary trial.
\item \code{integratedTrial}: A list of selected information for the integrated
trial, including \code{M}, \code{r}, \code{corr_known}, \code{MNew},
\code{rNew}, \code{selected}, \code{L}, \code{zL}, \code{theta},
\code{maxInformation}, \code{kMax}, \code{informationRates},
\code{efficacyBounds}, \code{futilityBounds}, \code{information},
and \code{byIntersectionBounds}, where \code{byIntersectionBounds} is
a data frame with columns \code{intersectionHypothesis}, \code{stage},
and \code{efficacyBounds}, representing the efficacy bounds for
each intersection hypothesis and each stage of analysis in the
integrated trial.
}
}
\description{
Calculates the conditional power for specified incremental
information, given the interim results, parameter value,
data-dependent changes in treatment selection,
the error spending function, and
the number and spacing of interim looks. Conversely,
calculates the incremental information required to attain
a specified conditional power, given the interim results,
parameter value, data-dependent changes in treatment selection,
the error spending function, and the number and spacing of interim looks.
}
\examples{

# Two active treatment arms are compared with a common control in a
# two-look time-to-event design using O'Brien–Fleming–type alpha spending.
# Suppose each active arm has a true hazard ratio of 0.75 versus control,
# and the total number of events across all three arms at the final analysis
# is 486. This corresponds to approximately 324 events for each active arm
# versus the common control. Under these assumptions, the trial has about
# 80\% power to detect the treatment effect in at least one active arm.

(des1 <- getDesign_mams(
  IMax = 324 / 4, theta = c(-log(0.75), -log(0.75)),
  M = 2, r = 1, kMax = 2, informationRates = c(1/2, 1),
  alpha = 0.025, typeAlphaSpending = "OF"))

# Now assume that, at the interim analysis, the observed hazard ratios for
# the two active arms versus control are 0.91 and 0.78, respectively. Using
# the rule “drop any arm with an observed hazard ratio > 0.9”, arm 1 is
# dropped. We then aim to achieve 80\% conditional power to detect a hazard
# ratio of 0.78 for the remaining arm at the final look. The analysis below
# indicates that the required total number of events for arm 2 versus control
# at the final analysis should be increased from 324 to 535.

(des2 <- adaptDesign_mams(
  betaNew = 0.2, M = 2, r = 1, corr_known = FALSE,
  L = 1, zL = c(-log(0.91), -log(0.78)) * sqrt(324 / 4 / 2),
  theta = c(-log(0.91), -log(0.78)),
  IMax = 324 / 4, kMax = 2, informationRates = c(1/2, 1),
  alpha = 0.025, typeAlphaSpending = "OF",
  MNew = 1, selected = 2, rNew = 1))

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