% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/RcppExports.R
\name{exitprob_seamless}
\alias{exitprob_seamless}
\title{Exit Probabilities for Phase 2/3 Seamless Design}
\usage{
exitprob_seamless(
  M = NA_integer_,
  r = 1,
  theta = NA_real_,
  corr_known = TRUE,
  K = NA_integer_,
  b = NULL,
  a = NULL,
  I = NULL
)
}
\arguments{
\item{M}{Number of active treatment arms in Phase 2.}

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

\item{theta}{A vector of length \eqn{M} representing the true treatment
effects for each active arm versus the common control.}

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

\item{K}{Number of sequential looks in Phase 3.}

\item{b}{A vector of efficacy boundaries (length \eqn{K+1}). The first
element is the efficacy boundary for the phase-2 max-Z statistic;
the remaining \eqn{K} elements are efficacy boundaries for the selected
arm in Phase 3.}

\item{a}{An optional vector of futility boundaries (length \eqn{K+1}).
The first element is the futility boundary for the phase-2 max-Z
statistic; the remaining \eqn{K} elements are futility boundaries for
the selected arm in Phase 3. If omitted, no futility stopping is
applied.}

\item{I}{A vector of information levels (length \eqn{K+1}) for any active
arm versus the common control. The first element is for Phase 2;
the remaining \eqn{K} elements are for the looks in Phase 3.}
}
\value{
A list containing the following components:
\itemize{
\item \code{exitProbUpper}: A vector of length \eqn{K + 1}. The first element
is the probability of stopping for efficacy in Phase 2; the remaining
elements are the probabilities of stopping for efficacy at each look in
Phase 3.
\item \code{exitProbLower}: A vector of length \eqn{K + 1}. The first element
is the probability of stopping for futility in Phase 2; the remaining
elements are the probabilities of stopping for futility at each look in
Phase 3.
\item \code{exitProbByArmUpper}: A \eqn{(K+1) \times M} matrix. The
\eqn{(k, m)}-th entry gives the probability of stopping for efficacy at
look \eqn{k} given that arm \eqn{m} is selected as best.
\item \code{exitProbByArmLower}: A \eqn{(K+1) \times M} matrix. The
\eqn{(k, m)}-th entry gives the probability of stopping for futility at
look \eqn{k} given that arm \eqn{m} is selected as best.
\item \code{selectAsBest}: A vector of length \eqn{M} containing the
probability that each active arm is selected to move on to Phase 3.
}

For backward compatibility, the list also contains:
\itemize{
\item \code{exitProb}: identical to \code{exitProbUpper}.
\item \code{exitProbByArm}: identical to \code{exitProbByArmUpper}.
}
}
\description{
Computes the upper and lower exit probabilities for a phase
2/3 seamless design. In Phase 2, multiple active arms are compared
against a common control arm. If the phase-2 max-Z statistic crosses the
efficacy boundary, the trial stops early for efficacy; if it falls below
the futility boundary, the trial stops early for futility. Otherwise, the
best-performing arm is selected to proceed to Phase 3, where it is tested
against the common control over multiple looks with upper and optional
lower stopping boundaries.
}
\details{
The function assumes a multivariate normal distribution for the Wald
statistics. The "best" arm is defined as the active arm with the largest
Z-statistic at the end of Phase 2 among designs that continue beyond the
phase-2 analysis.

\strong{Decision Rules:}
\itemize{
\item \strong{Phase 2 efficacy stop}: reject if the phase-2 max-Z statistic
satisfies \eqn{\max_m Z_m(I_0) \ge b_0}.
\item \strong{Phase 2 futility stop}: stop for futility if the phase-2 max-Z
statistic satisfies \eqn{\max_m Z_m(I_0) \le a_0}.
\item \strong{Continue to Phase 3}: if \eqn{a_0 < \max_m Z_m(I_0) < b_0},
select the arm with the largest phase-2 Z-statistic and continue with
that arm only.
\item \strong{Phase 3 efficacy stop}: at look \eqn{k}, reject if the selected
arm's Z-statistic exceeds the efficacy boundary and no earlier stop has
occurred.
\item \strong{Phase 3 futility stop}: at look \eqn{k}, stop for futility if
the selected arm's Z-statistic is below the futility boundary and no
earlier stop has occurred.
}

\strong{Design Assumptions:}
\itemize{
\item All active arms share the same information level in Phase 2.
\item Exactly one active arm is selected at the end of Phase 2 based on the
largest observed Z-statistic when the trial continues to Phase 3.
}
}
\examples{

# Setup: 2 active arms vs control in Phase 2; 1 selected arm vs control
# in Phase 3. Phase 3 has 2 sequential looks.

# Information levels: equal spacing over 3 looks based on a maximum of
# 110 patients per arm, SD = 1.0
I <- c(110 / (2 * 1.0^2) * seq(1, 3)/3)

# O'Brien-Fleming efficacy boundaries
b <- c(3.776605, 2.670463, 2.180424)

# No futility stopping
p0 <- exitprob_seamless(M = 2, theta = c(0, 0), K = 2, b = b, I = I)
cumsum(p0$exitProbUpper)

# Add futility stopping
a <- c(0, 0.5, b[3])
p1 <- exitprob_seamless(M = 2, theta = c(0.3, 0.5), K = 2, b = b, a = a, I = I)
cbind(
  cumulativeEfficacy = cumsum(p1$exitProbUpper),
  cumulativeFutility = cumsum(p1$exitProbLower)
)

}
\references{
Ping Gao, Yingqiu Li.
Adaptive two-stage seamless sequential design for clinical trials.
Journal of Biopharmaceutical Statistics, 2025, 35(4), 565-587.
}
\author{
Kaifeng Lu, \email{kaifenglu@gmail.com}
}
