---
title: "Introduction to FastSurvival"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to FastSurvival}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>"
)
```

# Overview

FastSurvival provides fast alternatives to the standard survival analysis
functions in the [survival](https://cran.r-project.org/package=survival)
package, together with a simulation layer for designing and evaluating
time-to-event trials. Every function is designed for repeated evaluation
inside large simulation loops, where the iterative or object-building
overhead of the standard implementations becomes a bottleneck. Core
computations are implemented in C++ via Rcpp.

```{r load-pkg}
library(FastSurvival)
```

# Function families

The package has two families of functions.

The estimation and testing functions operate on a single dataset and return
an S3 object with a `print()` method. `survfit_fast()` evaluates the
Kaplan-Meier estimate at a single time point. `survdiff_fast()` computes the
log-rank test and its weighted and stratified variants. `coxph_fast()`
returns a closed-form hazard ratio. `rmst_fast()` returns the restricted mean
survival time, and `wmst_fast()` the window mean survival time over an
interval. `milestone_fast()` compares survival at a milestone timepoint, and
`medsurv_fast()` compares median survival times. `maxcombo_fast()` computes the
max-combo test, `rmw_fast()` the robust modestly-weighted log-rank test, and
`wkm_fast()` the weighted Kaplan-Meier (Pepe-Fleming) test. `ahsw_fast()`
computes the average hazard with survival weight, and `ahr_fast()` the
Kalbfleisch-Prentice average hazard ratio.

The simulation functions support a full simulation study. `simdata_fast()`
generates individual patient data for one- or two-group trials.
`analysis_fast()` performs interim or sequential analyses of the simulated
data at one or more looks, and can compute any of the estimation and testing
statistics above, optionally within subgroups. `simsummary_fast()` aggregates
the operating characteristics from the analysis output against supplied
boundaries.

# A minimal example

The following example uses the `ovarian` dataset from the survival package,
with a one-sided test of treatment benefit (`side = 1`).

```{r quick}
library(survival)

# Single-time-point Kaplan-Meier estimate
ord <- order(ovarian$futime)
survfit_fast(ovarian$futime[ord], ovarian$fustat[ord],
             t_eval = 500, conf.type = "log")

# Log-rank test
survdiff_fast(ovarian$futime, ovarian$fustat, ovarian$rx,
              control = 1, side = 1)

# Hazard ratio via the Pike-Halley Estimator
coxph_fast(ovarian$futime, ovarian$fustat, ovarian$rx,
           control = 1, side = 1)
```

# Where to go next

Several further vignettes cover the package in depth. *Validation of
FastSurvival* checks numerical agreement with established packages on a real
clinical-trial dataset. *Speed comparison* quantifies the performance gain.
*Group sequential design with the simulation trio* demonstrates
`simdata_fast()`, `analysis_fast()`, and `simsummary_fast()` against a gsDesign
reference. Further applied vignettes work the simulation trio through
nonproportional-hazards, correlated multiple-endpoint, and multiregional
settings.

# References

Homma, G. (2025). One step from Pike to Cox: a closed-form hazard ratio
estimator. *Manuscript under review.*

Collett, D. (2014). *Modelling Survival Data in Medical Research* (3rd ed.).
Chapman and Hall/CRC.