R/lrstat-package.R

In lrstat: Power and Sample Size Calculation for Non-Proportional Hazards and Beyond

#' @name lrstat-package
#' @aliases lrstat-package
#'
#' @title Power and Sample Size Calculation for Non-Proportional Hazards
#' and Beyond
#'
#' @description A comprehensive clinical trial design and analysis package
#' with a focus on non-proportional hazards and weighted log-rank methods,
#' plus broad support for group sequential design, adaptive design,
#' multiplicity, dose-finding, and endpoint-specific power and sample size
#' calculations.
#'
#' @details
#' For proportional hazards, power is determined by the total number of
#' events and the constant hazard ratio together with information rates and
#' spending functions. For non-proportional hazards, the hazard ratio varies
#' over time and calendar time determines the mean and variance of the
#' weighted log-rank score statistic. The package uses the analytic approach
#' in Lu (2021) and approximates the variance-covariance matrix of
#' sequential statistics under the alternative by that under the null to
#' leverage the independent increments structure in Tsiatis (1982) for the
#' Fleming-Harrington family.
#'
#' The package capabilities can be grouped as follows:
#' \itemize{
#'   \item \strong{Time-to-event design under proportional and
#'     non-proportional hazards:} weighted log-rank statistics and design
#'     operating characteristics (for example \code{lrstat}, \code{lrpower},
#'     \code{lrsamplesize}, \code{lrsim}, \code{lrschoenfeld}), including
#'     equivalence settings, event prediction, accrual modeling, and calendar
#'     time determination (for example \code{accrual}, \code{caltime},
#'     \code{nevent}, \code{pevent}, \code{patrisk}, \code{natrisk},
#'     \code{getDurationFromNevents}, \code{getNeventsFromHazardRatio}).
#'   \item \strong{Group sequential and adaptive designs:} standard,
#'     adaptive, multi-arm multi-stage (MAMS), and seamless frameworks,
#'     including boundaries, conditional power, confidence intervals, and
#'     exit probabilities (for example \code{getDesign}, \code{adaptDesign},
#'     \code{getBound}, \code{getCP}, \code{getCI}, \code{getRCI},
#'     \code{getADCI}, \code{getADRCI}, \code{exitprob}, and their
#'     \code{_multiarm} and \code{_seamless} variants).
#'   \item \strong{Fixed and sequential sample size/power across endpoint
#'     types:} binary, continuous, ordinal/multinomial, paired,
#'     crossover/carryover, MMRM, repeated measures ANOVA, two-way ANOVA,
#'     Wilcoxon, Fisher's exact, McNemar, one-sample exact, agreement,
#'     logistic regression, and negative binomial endpoints (for example
#'     \code{getDesign*}, \code{power*Exact}, \code{samplesize*Exact},
#'     \code{kmpower}, \code{rmpower}, \code{nbpower}, and associated
#'     \code{*samplesize} and \code{*equiv} functions).
#'   \item \strong{Multiplicity and graphical procedures:} weighted
#'     Bonferroni and graph-based updates, Bonferroni mixtures of weighted
#'     Simes and Dunnett, and gatekeeping procedures for multiple hypotheses
#'     (for example \code{fadjpbon}, \code{fadjpsim}, \code{fadjpdun},
#'     \code{fseqbon}, \code{fstp2seq}, \code{fstdmix}, \code{fmodmix},
#'     \code{fwgtmat}, \code{updateGraph}).
#'   \item \strong{Early-phase and dose-finding tools:} Simon's two-stage,
#'     Bayesian Simon designs, mTPI-2, and BOIN utilities
#'     (for example \code{simon2stage}, \code{simonBayesAnalysis},
#'     \code{simonBayesSim}, \code{mTPI2Table}, \code{BOINTable}).
#'   \item \strong{Estimation, confidence intervals, and supporting
#'     utilities:} Clopper-Pearson, exact risk ratio/risk difference,
#'     Brookmeyer-Crowley survival quantiles, Miettinen-Nurminen and REML
#'     intervals/statistics for stratified measures, Hedges' g,
#'     piecewise-exponential distribution tools, multivariate normal
#'     integration, and model diagnostics
#'     (for example \code{ClopperPearsonCI}, \code{riskRatioExactCI},
#'     \code{riskDiffExactCI}, \code{survQuantile}, \code{mnRiskDiffCI},
#'     \code{remlRiskDiff}, \code{hedgesg}, \code{dtpwexp}, \code{ptpwexp},
#'     \code{qtpwexp}, \code{rtpwexp}, \code{pbvnorm}, \code{pmvnormr},
#'     \code{qmvnormr}, \code{phregr}, \code{liferegr},
#'     \code{residuals_phregr}, \code{survfit_phregr}, \code{zph_phregr}).
#'   \item \strong{Interactive use:} a bundled Shiny interface for
#'     exploratory design workflows (\code{runShinyApp_lrstat}).
#' }
#'
#' The development of lrstat was strongly influenced by \code{rpact}, with
#' argument naming aligned where possible for ease of adoption. Key
#' differences include direct approximation (rather than Schoenfeld-based
#' approximation) for weighted log-rank design calculations, explicit use of
#' \code{accrualDuration} to define the accrual end, and treatment of final
#' stage trial outcome when early futility stopping does not occur.
#'
#' @author Kaifeng Lu, \email{kaifenglu@@gmail.com}
#'
#' @references
#' Anastasios A. Tsiatis. Repeated significance testing for a general class
#' of statistics used in censored survival analysis. J Am Stat Assoc.
#' 1982;77:855-861.
#'
#' Christopher Jennison, Bruce W. Turnbull. Group Sequential Methods with
#' Applications to Clinical Trials. Chapman & Hall/CRC: Boca Raton, 2000,
#' ISBN:0849303168
#'
#' Kaifeng Lu. Sample size calculation for logrank test and prediction of
#' number of events over time. Pharm Stat. 2021;20:229-244.
#'
#'
#' @seealso rpact, gsDesign
#'
#' @examples
#' lrpower(kMax = 2, informationRates = c(0.8, 1),
#'         criticalValues = c(2.250, 2.025), accrualIntensity = 20,
#'         piecewiseSurvivalTime = c(0, 6),
#'         lambda1 = c(0.0533, 0.0309), lambda2 = c(0.0533, 0.0533),
#'         gamma1 = 0.00427, gamma2 = 0.00427,
#'         accrualDuration = 22, followupTime = 18)
#'
#' @useDynLib lrstat, .registration = TRUE
#' @importFrom Rcpp evalCpp
#' @importFrom RcppParallel setThreadOptions RcppParallelLibs
#' @importFrom parallel detectCores
#' @importFrom stats as.formula complete.cases dgamma dlogis dnorm formula
#' @importFrom stats integrate model.frame model.matrix na.omit na.pass
#' @importFrom stats optimize pbeta pchisq pf plogis pnorm pt qbeta
#' @importFrom stats qchisq qf qlogis qnorm qt reformulate runif terms
#' @importFrom stats uniroot var
#' @importFrom ggplot2 aes annotate element_text geom_step ggplot labs
#' @importFrom ggplot2 scale_linewidth_manual theme theme_bw
#' @importFrom plotly layout plot_ly
#' @importFrom rlang .data
#' @importFrom shiny shinyAppDir
#'
NULL