---
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. `milestone_fast()` compares survival at a milestone timepoint.
`maxcombo_fast()` computes the max-combo test. `rmw_fast()` computes the
robust modestly-weighted log-rank test. `ahsw_fast()` computes the
average hazard with survival weight. `ahr_fast()` computes 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. `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.

```{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 = 2)

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

# Where to go next

Three further vignettes cover the package in depth. *Validation of
FastSurvival* checks numerical agreement with established packages. *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.

# 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.