% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lrsim.R
\name{lrsim3a}
\alias{lrsim3a}
\title{Log-Rank Test Simulation for Three Arms}
\usage{
lrsim3a(
  kMax = 1,
  hazardRatioH013 = 1,
  hazardRatioH023 = 1,
  hazardRatioH012 = 1,
  allocation1 = 1,
  allocation2 = 1,
  allocation3 = 1,
  accrualTime = 0,
  accrualIntensity = NA,
  piecewiseSurvivalTime = 0,
  stratumFraction = 1,
  lambda1 = NA,
  lambda2 = NA,
  lambda3 = NA,
  gamma1 = 0,
  gamma2 = 0,
  gamma3 = 0,
  n = NA,
  followupTime = NA,
  fixedFollowup = FALSE,
  rho1 = 0,
  rho2 = 0,
  plannedEvents = NA,
  plannedTime = NA,
  maxNumberOfIterations = 1000,
  maxNumberOfRawDatasetsPerStage = 0,
  seed = 0,
  nthreads = 0
)
}
\arguments{
\item{kMax}{The maximum number of stages.}

\item{hazardRatioH013}{Hazard ratio under the null hypothesis for arm 1
versus arm 3. Defaults to 1 for superiority test.}

\item{hazardRatioH023}{Hazard ratio under the null hypothesis for arm 2
versus arm 3. Defaults to 1 for superiority test.}

\item{hazardRatioH012}{Hazard ratio under the null hypothesis for arm 1
versus arm 2. Defaults to 1 for superiority test.}

\item{allocation1}{Number of subjects in Arm A in
a randomization block. Defaults to 1 for equal randomization.}

\item{allocation2}{Number of subjects in Arm B in
a randomization block. Defaults to 1 for equal randomization.}

\item{allocation3}{Number of subjects in Arm C in
a randomization block. Defaults to 1 for equal randomization.}

\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{lambda1}{A vector of hazard rates for the event in each analysis
time interval by stratum for arm 1.}

\item{lambda2}{A vector of hazard rates for the event in each analysis
time interval by stratum for arm 2.}

\item{lambda3}{A vector of hazard rates for the event in each analysis
time interval by stratum for arm 3.}

\item{gamma1}{The hazard rate for exponential dropout. A vector of
hazard rates for piecewise exponential dropout applicable for all
strata, or a vector of hazard rates for dropout in each analysis time
interval by stratum for arm 1.}

\item{gamma2}{The hazard rate for exponential dropout. A vector of
hazard rates for piecewise exponential dropout applicable for all
strata, or a vector of hazard rates for dropout in each analysis time
interval by stratum for arm 2.}

\item{gamma3}{The hazard rate for exponential dropout. A vector of
hazard rates for piecewise exponential dropout applicable for all
strata, or a vector of hazard rates for dropout in each analysis time
interval by stratum for arm 3.}

\item{n}{Sample size.}

\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}{The planned cumulative total number of events at
Look 1 to Look \code{kMax} for Arms A and C combined.}

\item{plannedTime}{The calendar times for the analyses. To use calendar
time to plan the analyses, \code{plannedEvents} should be missing.}

\item{maxNumberOfIterations}{The number of simulation iterations.
Defaults to 1000.}

\item{maxNumberOfRawDatasetsPerStage}{The number of raw datasets per
stage to extract.}

\item{seed}{The seed to reproduce the simulation results.}

\item{nthreads}{The number of threads to use in simulations (0 means
the default RcppParallel behavior).}
}
\value{
A list with 2 components:
\itemize{
\item \code{sumdata}: A data frame of summary data by iteration and stage:
\itemize{
\item \code{iterationNumber}: The iteration number.
\item \code{eventsNotAchieved}: Whether the target number of events
is not achieved for the iteration.
\item \code{stageNumber}: The stage number, covering all stages even if
the trial stops at an interim look.
\item \code{analysisTime}: The time for the stage since trial start.
\item \code{accruals1}: The number of subjects enrolled at the stage for
the active treatment 1 group.
\item \code{accruals2}: The number of subjects enrolled at the stage for
the active treatment 2 group.
\item \code{accruals3}: The number of subjects enrolled at the stage for
the control group.
\item \code{totalAccruals}: The total number of subjects enrolled at
the stage.
\item \code{events1}: The number of events at the stage for
the active treatment 1 group.
\item \code{events2}: The number of events at the stage for
the active treatment 2 group.
\item \code{events3}: The number of events at the stage for
the control group.
\item \code{totalEvents}: The total number of events at the stage.
\item \code{dropouts1}: The number of dropouts at the stage for
the active treatment 1 group.
\item \code{dropouts2}: The number of dropouts at the stage for
the active treatment 2 group.
\item \code{dropouts3}: The number of dropouts at the stage for
the control group.
\item \code{totalDropouts}: The total number of dropouts at the stage.
\item \code{uscore13}: The log-rank test score statistic comparing the
active treatment 1 to the control.
\item \code{vscore13}: The log-rank test variance statistic comparing the
active treatment 1 to the control.
\item \code{logRankStatistic13}: The log-rank test Z-statistic
comparing the active treatment 1 to the control.
\item \code{uscore23}: The log-rank test score statistic comparing the
active treatment 2 to the control.
\item \code{vscore23}: The log-rank test variance statistic comparing the
active treatment 2 to the control.
\item \code{logRankStatistic23}: The log-rank test Z-statistic
comparing the active treatment 2 to the control.
\item \code{uscore12}: The log-rank test score statistic comparing the
active treatment 1 to the active treatment 2.
\item \code{vscore12}: The log-rank test variance statistic comparing the
active treatment 1 to the active treatment 2.
\item \code{logRankStatistic12}: The log-rank test Z-statistic
comparing the active treatment 1 to the active treatment 2.
}
\item \code{rawdata} (exists if \code{maxNumberOfRawDatasetsPerStage} is a
positive integer): A data frame for subject-level data for selected
replications, containing the following variables:
\itemize{
\item \code{iterationNumber}: The iteration number.
\item \code{stageNumber}: The stage under consideration.
\item \code{analysisTime}: The time for the stage since trial start.
\item \code{subjectId}: The subject ID.
\item \code{arrivalTime}: The enrollment time for the subject.
\item \code{stratum}: The stratum for the subject.
\item \code{treatmentGroup}: The treatment group (1, 2, or 3) for
the subject.
\item \code{survivalTime}: The underlying survival time for the subject.
\item \code{dropoutTime}: The underlying dropout time for the subject.
\item \code{timeUnderObservation}: The time under observation
since randomization for the subject.
\item \code{event}: Whether the subject experienced the event.
\item \code{dropoutEvent}: Whether the subject dropped out.
}
}
}
\description{
Performs simulation for three-arm group sequential trials
based on weighted log-rank test. The looks are driven by the total
number of events in Arm A and Arm C combined. Alternatively,
the analyses can be planned to occur at specified calendar times.
}
\examples{

sim1 <- lrsim3a(
  kMax = 3,
  allocation1 = 2,
  allocation2 = 2,
  allocation3 = 1,
  accrualTime = c(0, 8),
  accrualIntensity = c(10, 28),
  piecewiseSurvivalTime = 0,
  lambda1 = log(2)/12*0.60,
  lambda2 = log(2)/12*0.70,
  lambda3 = log(2)/12,
  n = 700,
  plannedEvents = c(186, 259, 295),
  maxNumberOfIterations = 1000,
  maxNumberOfRawDatasetsPerStage = 1,
  seed = 314159,
  nthreads = 1)

head(sim1$sumdata)
head(sim1$rawdata)

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