% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/RcppExports.R
\name{getDesign}
\alias{getDesign}
\title{Power and Sample Size for a Generic Group Sequential Design}
\usage{
getDesign(
  beta = NA_real_,
  IMax = NA_real_,
  theta = NA_real_,
  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_,
  varianceRatio = 1
)
}
\arguments{
\item{beta}{The type II error.}

\item{IMax}{The maximum information. Either \code{beta} or \code{IMax}
should be provided while the other one should be missing.}

\item{theta}{The parameter value. Null hypothesis is at \code{theta = 0},
and the alternative hypothesis is one-sided for \code{theta > 0}.}

\item{kMax}{The maximum number of stages.}

\item{informationRates}{The information rates. Fixed prior to the trial.
Defaults to \code{(1:kMax) / kMax} if left unspecified.}

\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}{Upper boundaries on the z-test statistic scale
for stopping for efficacy.}

\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}{Lower boundaries on the z-test statistic scale
for stopping for futility at stages \code{1, ..., kMax-1}. Defaults to
\code{rep(-8, kMax-1)} if left unspecified. The futility bounds are
non-binding for the calculation of critical values.}

\item{futilityCP}{The futility bounds on the conditional power scale.}

\item{futilityTheta}{The futility bounds on the parameter scale.}

\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 vector of length \code{kMax} for the error spending
time at each analysis. Defaults to missing, in which case, it is the
same as \code{informationRates}.}

\item{varianceRatio}{The ratio of the variance under H0 to the
variance under H1.}
}
\value{
An S3 class \code{design} object with three components:
\itemize{
\item \code{overallResults}: A data frame containing the following variables:
\itemize{
\item \code{overallReject}: The overall rejection probability.
\item \code{alpha}: The 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{kMax}: The number of stages.
\item \code{theta}: The parameter value.
\item \code{information}: The maximum information.
\item \code{expectedInformationH1}: The expected information under H1.
\item \code{expectedInformationH0}: The expected information under H0.
\item \code{drift}: The drift parameter, equal to
\code{theta*sqrt(information)}.
\item \code{inflationFactor}: The inflation factor (relative to the
fixed design).
}
\item \code{byStageResults}: A data frame containing the following variables:
\itemize{
\item \code{informationRates}: The information rates.
\item \code{efficacyBounds}: The efficacy boundaries on the Z-scale.
\item \code{futilityBounds}: The futility boundaries on the Z-scale.
\item \code{rejectPerStage}: The probability for efficacy stopping.
\item \code{futilityPerStage}: The probability for futility stopping.
\item \code{cumulativeRejection}: The cumulative probability for efficacy
stopping.
\item \code{cumulativeFutility}: The cumulative probability for futility
stopping.
\item \code{cumulativeAlphaSpent}: The cumulative alpha spent.
\item \code{efficacyTheta}: The efficacy boundaries on the parameter
scale.
\item \code{futilityTheta}: The futility boundaries on the parameter
scale.
\item \code{efficacyP}: The efficacy boundaries on the p-value scale.
\item \code{futilityP}: The futility boundaries on the p-value scale.
\item \code{information}: The cumulative information.
\item \code{efficacyStopping}: Whether to allow efficacy stopping.
\item \code{futilityStopping}: Whether to allow futility stopping.
\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 containing the following input parameters:
\itemize{
\item \code{typeAlphaSpending}: The type of alpha spending.
\item \code{parameterAlphaSpending}: The parameter value for alpha
spending.
\item \code{userAlphaSpending}: The user defined alpha spending.
\item \code{typeBetaSpending}: The type of beta spending.
\item \code{parameterBetaSpending}: The parameter value for beta
spending.
\item \code{userBetaSpending}: The user defined beta spending.
\item \code{spendingTime}: The error spending time at each analysis.
\item \code{varianceRatio}: The ratio of the variance under H0
to the variance under H1.
}
}
}
\description{
Obtains the maximum information and stopping boundaries
for a generic group sequential design assuming a constant treatment
effect, or obtains the power given the maximum information and
stopping boundaries.
}
\details{
The function determines efficacy and futility bounds based on the inputs
provided, following a clear priority order.

\strong{Efficacy bounds:}
If \code{criticalValues} are supplied, they take precedence and all
alpha-spending parameters are ignored. Otherwise, efficacy bounds are
derived from the specified alpha-spending function.

\strong{Futility bounds:}
Futility inputs are evaluated in the following order of priority:
\enumerate{
\item If \code{futilityBounds} are provided, they override all other
futility-related inputs (\code{futilityCP}, \code{futilityTheta},
and beta-spending parameters).

\item If \code{futilityBounds} are not provided but \code{futilityCP}
is specified, then \code{futilityTheta} and beta-spending parameters
are ignored.

\item If only \code{futilityTheta} is provided, beta-spending parameters
are ignored.

\item If none of \code{futilityBounds}, \code{futilityCP},
or \code{futilityTheta} are specified, futility bounds are computed
using the beta-spending approach.
}
}
\examples{

# Example 1: obtain the maximum information given power
(design1 <- getDesign(
  beta = 0.2, theta = -log(0.7),
  kMax = 2, informationRates = c(0.5,1),
  alpha = 0.025, typeAlphaSpending = "sfOF",
  typeBetaSpending = "sfP"))

# Example 2: obtain power given the maximum information
(design2 <- getDesign(
  IMax = 72.5, theta = -log(0.7),
  kMax = 3, informationRates = c(0.5, 0.75, 1),
  alpha = 0.025, typeAlphaSpending = "sfOF",
  typeBetaSpending = "sfP"))

}
\references{
Christopher Jennison, Bruce W. Turnbull.
Group Sequential Methods with Applications to Clinical Trials.
Chapman & Hall/CRC: Boca Raton, 2000, ISBN:0849303168
}
\author{
Kaifeng Lu, \email{kaifenglu@gmail.com}
}
