% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/RcppExports.R
\name{nbpower1s}
\alias{nbpower1s}
\title{Power for One-Sample Negative Binomial Rate}
\usage{
nbpower1s(
  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,
  futilityRate = NULL,
  typeBetaSpending = "none",
  parameterBetaSpending = NA_real_,
  lambdaH0 = NA_real_,
  accrualTime = 0L,
  accrualIntensity = NA_real_,
  piecewiseSurvivalTime = 0L,
  stratumFraction = 1L,
  kappa = NA_real_,
  lambda = NA_real_,
  gamma = 0L,
  accrualDuration = NA_real_,
  followupTime = NA_real_,
  fixedFollowup = FALSE,
  spendingTime = NA_real_,
  studyDuration = NA_real_
)
}
\arguments{
\item{kMax}{The maximum number of stages.}

\item{informationRates}{The information rates.
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}{A vector of length \code{kMax - 1} for the futility
bounds on the conditional power scale.}

\item{futilityRate}{A vector of length \code{kMax - 1} for the
futility bounds on the rate 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, 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{lambdaH0}{The rate parameter of the negative binomial distribution
under the null hypothesis.}

\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{kappa}{The dispersion parameter (reciprocal of the shape parameter
of the gamma mixing distribution) of the negative binomial
distribution by stratum.}

\item{lambda}{The rate parameter of the negative binomial distribution
under the alternative hypothesis by stratum.}

\item{gamma}{The hazard rate for exponential dropout or a vector of
hazard rates for piecewise exponential dropout by stratum.
Defaults to 0 for no dropout.}

\item{accrualDuration}{Duration of the enrollment period.}

\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{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{studyDuration}{Study duration for fixed follow-up design.
Defaults to missing, which is to be replaced with the sum of
\code{accrualDuration} and \code{followupTime}. If provided,
the value is allowed to be less than the sum of \code{accrualDuration}
and \code{followupTime}.}
}
\value{
An S3 class \code{nbpower1s} object with 3 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{numberOfEvents}: The total number of events.
\item \code{numberOfDropouts}: The total number of dropouts.
\item \code{numbeOfSubjects}: The total number of subjects.
\item \code{exposure}: The total exposure.
\item \code{studyDuration}: The total study duration.
\item \code{information}: The maximum information.
\item \code{expectedNumberOfEvents}: The expected number of events.
\item \code{expectedNumberOfDropouts}: The expected number of dropouts.
\item \code{expectedNumberOfSubjects}: The expected number of subjects.
\item \code{expectedExposure}: The expected exposure.
\item \code{expectedStudyDuration}: The expected study duration.
\item \code{expectedInformation}: The expected information.
\item \code{accrualDuration}: The accrual duration.
\item \code{followupTime}: The follow-up duration.
\item \code{fixedFollowup}: Whether a fixed follow-up design is used.
\item \code{kMax}: The number of stages.
\item \code{lambdaH0}: The rate parameter of the negative binomial
distribution under the null hypothesis.
\item \code{lambda}: The overall rate parameter of the negative binomial
distribution under the alternative hypothesis.
}
\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{numberOfEvents}: The number of events.
\item \code{numberOfDropouts}: The number of dropouts.
\item \code{numberOfSubjects}: The number of subjects.
\item \code{exposure}: The exposure.
\item \code{analysisTime}: The average time since trial start.
\item \code{efficacyRate}: The efficacy boundaries on the rate scale.
\item \code{futilityRate}: The futility boundaries on the rate 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{settings}: A list containing the following input parameters:
\code{typeAlphaSpending}, \code{parameterAlphaSpending},
\code{userAlphaSpending}, \code{typeBetaSpending},
\code{parameterBetaSpending}, \code{accrualTime},
\code{accuralIntensity}, \code{piecewiseSurvivalTime},
\code{stratumFraction}, \code{kappa}, \code{lambda}, \code{gamma},
and \code{spendingTime}.
}
}
\description{
Estimates the power, stopping probabilities, and expected
sample size in a one-group negative binomial design.
}
\examples{
# Example 1: Variable follow-up design

nbpower1s(kMax = 2, informationRates = c(0.5, 1),
          alpha = 0.025, typeAlphaSpending = "sfOF",
          lambdaH0 = 0.125, accrualIntensity = 500,
          stratumFraction = c(0.2, 0.8),
          kappa = c(3, 5), lambda = c(0.0875, 0.085),
          gamma = 0, accrualDuration = 1.25,
          followupTime = 2.75, fixedFollowup = FALSE)

# Example 2: Fixed follow-up design

nbpower1s(kMax = 2, informationRates = c(0.5, 1),
          alpha = 0.025, typeAlphaSpending = "sfOF",
          lambdaH0 = 8.4, accrualIntensity = 40,
          kappa = 3, lambda = 0.5*8.4,
          gamma = 0, accrualDuration = 1.5,
          followupTime = 0.5, fixedFollowup = TRUE)

}
\seealso{
\code{\link{nbstat}}
}
\author{
Kaifeng Lu, \email{kaifenglu@gmail.com}
}
