---
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. Collett (2014) gives the
methodological background of the standard methods they implement.

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, the Pike-Halley Estimator. `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-group, two-group, or multi-arm
trials.
`cutoff_fast()` determines the calendar time of every analysis look in every
simulated trial from combined event and calendar-time rules.
`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. `switch_fast()` applies
treatment switching to the simulated data, at progression or after an interim
analysis. `pairwise_fast()` compares each experimental arm of a multi-arm
trial with a shared control. `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, eval = requireNamespace("survival", quietly = TRUE)}
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)
```

# Formulas, data frames, and plots

For the analysis of a single data set the functions also accept a model
formula with a data frame, as the functions of the survival package do. The
control group is then the first level of the group variable, unless
`control` is given. Inside simulation loops the vector interface remains the
faster choice. Every result has an `as.data.frame()` method that returns its
estimates and tests with the same columns, and `coef()` and `confint()`
methods for the estimates; ratios are reported on the log scale.

```{r formula, eval = requireNamespace("survival", quietly = TRUE)}
fit <- coxph_fast(Surv(futime, fustat) ~ rx, data = ovarian, side = 1)
as.data.frame(fit)
exp(confint(fit))

as.data.frame(rmst_fast(Surv(futime, fustat) ~ rx, data = ovarian,
                        tau = 500))
```

`kmcurve_fast()` builds the Kaplan-Meier curves of a data set, and its
`plot()` method can add the numbers at risk below the curves.

```{r km-plot, eval = requireNamespace("survival", quietly = TRUE), fig.width = 7, fig.height = 5}
km <- kmcurve_fast(Surv(futime, fustat) ~ rx, data = ovarian)
plot(km, risk_table = TRUE, conf.style = "band")
```

# 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 functions through
nonproportional-hazards, correlated multiple-endpoint, multi-arm,
multiregional, and treatment-switching settings, and *Using your own data
generator* analyzes data generated outside the package with the same
functions.

# References

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