% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lrsim_seamless.R
\name{lrsim_seamless}
\alias{lrsim_seamless}
\title{Log-Rank Test Simulation for Phase 2/3 Seamless Design}
\usage{
lrsim_seamless(
  M = 2,
  K = 1,
  criticalValues = NA,
  futilityBounds = NULL,
  hazardRatioH0s = 1,
  allocations = 1,
  accrualTime = 0,
  accrualIntensity = NA,
  piecewiseSurvivalTime = 0,
  stratumFraction = 1,
  lambdas = NULL,
  gammas = NULL,
  n = NA,
  followupTime = NA,
  fixedFollowup = FALSE,
  rho1 = 0,
  rho2 = 0,
  plannedEvents = NA,
  plannedTime = NA,
  maxNumberOfIterations = 1000,
  maxNumberOfRawDatasetsPerStage = 0,
  seed = 0,
  nthreads = 0
)
}
\arguments{
\item{M}{Number of active treatment arms in Phase 2.}

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

\item{criticalValues}{Numeric vector of length \eqn{K + 1} giving the
critical value for the Wald statistic at each look (Look 1 through
Look \eqn{K + 1}). Decision rule:
\itemize{
\item At Look 1, compute the Wald statistic for each active arm versus the
common control. If the maximum of these statistics exceeds the Look 1
critical value, stop for efficacy.
\item If the Look 1 stopping rule is not met, select the active arm with the
largest Wald statistic as the "best" arm and continue with that arm
only versus control at subsequent looks.
\item For each look \eqn{j = 2,\ldots,K+1}, compare the selected arm to
control; if its Wald statistic exceeds the Look \eqn{j} critical
value, stop for efficacy; otherwise continue.
\item If no critical value is exceeded by Look \eqn{K + 1}, the procedure
ends without rejection.
}}

\item{futilityBounds}{Numeric vector of length \eqn{K} giving the futility
boundaries for Phase 2 and the first \eqn{K-1} looks in Phase 3.
The study stops for futility:
\itemize{
\item in Phase 2 if all active treatment arms cross the phase-2 futility
boundary;
\item in Phase 3 if the selected arm crosses the futility boundary at an
interim look;
If omitted, no interim futility stopping is applied.
}}

\item{hazardRatioH0s}{Numeric vector of length \eqn{M}. Hazard ratios
under \eqn{H_0} for each active arm versus the common control. Defaults
to 1 for superiority tests.}

\item{allocations}{Integer or integer vector of length \eqn{M + 1}.
Number of subjects per arm within a randomization block. A single value
implies equal allocation; defaults to 1.}

\item{accrualTime}{A vector that specifies the starting time of
piecewise Poisson enrollment time intervals. Must start with 0, e.g.,
\code{c(0, 3)} breaks the time axis into 2 accrual intervals:
\eqn{[0, 3)} and \eqn{[3, \infty)}.}

\item{accrualIntensity}{A vector of accrual intensities. One for
each accrual time interval.}

\item{piecewiseSurvivalTime}{A vector that specifies the starting time of
piecewise exponential survival time intervals. Must start with 0, e.g.,
\code{c(0, 6)} breaks the time axis into 2 event intervals:
\eqn{[0, 6)} and \eqn{[6, \infty)}.
Defaults to 0 for exponential distribution.}

\item{stratumFraction}{A vector of stratum fractions that sum to 1.
Defaults to 1 for no stratification.}

\item{lambdas}{List of length \eqn{M} (one element per arm). Each element
is a scalar or a numeric vector of event hazard rates for the
corresponding arm, given by analysis interval and stratum as required
by the simulation.}

\item{gammas}{List of length \eqn{M} (one element per arm). Each element
is a scalar or a numeric vector of dropout hazard rates for the
corresponding arm, by analysis interval and stratum.}

\item{n}{Planned total sample size across all active arms and control.}

\item{followupTime}{Follow-up time for the last enrolled subject.}

\item{fixedFollowup}{Whether a fixed follow-up design is used.
Defaults to \code{FALSE} for variable follow-up.}

\item{rho1}{The first parameter of the Fleming-Harrington family of
weighted log-rank test. Defaults to 0 for conventional log-rank test.}

\item{rho2}{The second parameter of the Fleming-Harrington family of
weighted log-rank test. Defaults to 0 for conventional log-rank test.}

\item{plannedEvents}{Numeric vector of length \eqn{K + 1} giving the
planned cumulative number of events to trigger Look 1 through Look
\eqn{K + 1}. Each entry refers to the combined events for the first
active arm and the common control. Use \code{plannedEvents} to schedule
event-driven looks.}

\item{plannedTime}{Numeric vector of calendar times for the analyses.
If \code{plannedTime} is supplied, analyses are scheduled by calendar
time and \code{plannedEvents} should be left missing.}

\item{maxNumberOfIterations}{Number of Monte Carlo replications.
Defaults to 1000.}

\item{maxNumberOfRawDatasetsPerStage}{Number of subject-level
raw datasets to retain per stage (for selected replications).}

\item{seed}{Random seed for reproducibility.}

\item{nthreads}{Number of threads for parallel simulation.
Use 0 to accept the default RcppParallel behavior.}
}
\value{
An S3 object of class \code{"lrsim_seamless"} with these components:
\itemize{
\item \code{overview}: A list summarizing trial-level results and settings:
\itemize{
\item \code{selectAsBest}: Probability of selecting each active arm as
the best arm at the end of phase 2.
\item \code{rejectPerStage}: Probability of rejecting the null for each
active arm at each stage.
\item \code{futilityPerStage}: Probability of futility stopping for each
active arm at each stage.
\item \code{cumulativeRejection}: Cumulative probability of rejection by stage.
\item \code{cumulativeFutility}: Cumulative futility stopping probabilities
by stage.
\item \code{numberOfEvents}: Cumulative event counts by stage, including
events from all arms in stage 1 and events from the selected arm
and control in later stages.
\item \code{numberOfDropouts}: Cumulative dropouts by stage.
\item \code{numberOfSubjects}: Cumulative enrollments by stage.
\item \code{analysisTime}: Average calendar time for each stage among
replications that reached that stage.
\item \code{overallReject}: Overall probability of rejecting the null
by trial end.
\item \code{overallFutility}: Overall probability of stopping for futility
by trial end.
\item \code{expectedNumberOfEvents}: Expected cumulative events at trial end.
\item \code{expectedNumberOfDropouts}: Expected cumulative dropouts at trial end.
\item \code{expectedNumberOfSubjects}: Expected cumulative enrollments
at trial end.
\item \code{expectedStudyDuration}: Expected study duration.
\item \code{criticalValues}: The input critical values for each stage.
\item \code{futilityBounds}: The input futility boundaries for each stage.
\item \code{hazardRatioH0s}: The input hazard ratios under \eqn{H_0}.
\item \code{useEvents}: Logical indicating whether analyses were event-driven.
\item \code{numberOfIterations}: Number of simulation iterations performed.
\item \code{n}: Planned total sample size.
\item \code{fixedFollowup}: Logical indicating whether fixed follow-up was used.
\item \code{rho1}, \code{rho2}: Fleming–Harrington weighting parameters used.
\item \code{M}: Number of active arms in Phase 2.
\item \code{K}: Number of sequential looks in Phase 3.
}
\item \code{sumdata1}: Data frame summarizing each iteration, stage, and
treatment group:
\itemize{
\item \code{iterationNumber}, \code{eventsNotAchieved},
\code{stopStage}, \code{stageNumber},
\code{analysisTime}, \code{treatmentGroup}, \code{accruals},
\code{events}, \code{dropouts}.
\item For each stage the final row summarizes the overall study
(all arms combined).
}
\item \code{summdata2}: Data frame summarizing log-rank statistics by iteration,
stage, and active arm:
\itemize{
\item \code{iterationNumber}, \code{bestArm}, \code{stopStage},
\code{stageNumber}, \code{analysisTime}, \code{activeArm},
\code{totalAccruals}, \code{totalEvents}, \code{totalDropouts},
\code{uscore}, \code{vscore}, \code{logRankStatistic},
\code{reject}, \code{futility}.
\item For each active arm, total accruals, events, and dropouts refer to
the combined counts for that arm and the common control at that stage.
}
\item \code{rawdata} (present when \code{maxNumberOfRawDatasetsPerStage} > 0):
Subject-level data for selected replications with variables:
\itemize{
\item \code{iterationNumber}, \code{stopStage}, \code{stageNumber},
\code{analysisTime}, \code{subjectId}, \code{arrivalTime},
\code{stratum}, \code{treatmentGroup},
\code{survivalTime}, \code{dropoutTime}, \code{timeUnderObservation},
\code{event}, \code{dropoutEvent}.
}
}
}
\description{
Simulate phase 2/3 seamless design using a weighted
log-rank test. Analyses can be triggered either by the cumulative number
of events (combined for an active arm and the common control) or by
pre-specified calendar times.
}
\examples{
(sim1 <- lrsim_seamless(
  M = 2,
  K = 2,
  criticalValues = c(3.882, 2.733, 2.222),
  futilityBounds = c(0.259, 1.201),
  accrualTime = c(0, 8),
  accrualIntensity = c(10, 28),
  piecewiseSurvivalTime = 0,
  lambdas = list(log(2)/12*0.5, log(2)/12*0.7, log(2)/12),
  n = 700,
  plannedEvents = c(42, 84, 126),
  maxNumberOfIterations = 10000,
  maxNumberOfRawDatasetsPerStage = 1,
  seed = 314159,
  nthreads = 0))

}
\author{
Kaifeng Lu, \email{kaifenglu@gmail.com}
}
