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

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

survivalGPU performs survival analysis on GPU-accelerated hardware. Classical survival models don't scale well to large datasets or to heavy bootstrap resampling on CPU: survivalGPU runs the core computations on the GPU to make both practical, while still working without one (CPU fallback).


## Two models

- **`coxphGPU()`**: Cox proportional hazards regression[^cox1] [^cox2], with the Efron or Breslow handling of ties. It takes the same inputs as `survival::coxph()`[^survival], and its results work with the usual tools of the survival package (`summary()`, `cox.zph()`, `survminer` plots, ...). See `vignette("coxPH", package = "survivalGPU")`.
- **`wceGPU()`**: Weighted Cumulative Exposure (WCE)[^wce], which models how the effect of a time-varying exposure (e.g. a drug) depends on how long ago it was received, with a weight function estimated by splines. It takes the same inputs as `WCE::WCE()`[^wcepkg], and `HR()` computes hazard ratios between exposure profiles. See `vignette("WCE", package = "survivalGPU")`.

Both models support **bootstrap resampling**, as a separate step after the fit: `bootstrap()` refits the model on many patient-level resamples of the data, processed in parallel batches (`batchsize`) on the GPU, to get bootstrap confidence intervals. For `wceGPU()`, several numbers of knots can be given (e.g. `nknots = 1:3`): the best one is selected by AIC or BIC, again in every bootstrap replicate, so that the confidence intervals also account for the uncertainty on this choice.


## A first example

```{r}
library(reticulate)
use_virtualenv("survivalGPU") # the Python environment, see below

library(survivalGPU)
library(survival)

use_cuda() # TRUE if a GPU is detected, FALSE if survivalGPU runs on CPU

data <- lung
data$status <- data$status - 1 # event coded as 0/1
data$id <- seq_len(nrow(data))  # one row per patient

fit <- coxphGPU(Surv(time, status) ~ age + sex, data = data,
                x = TRUE, patient_id = "id") # both needed by bootstrap()
fit <- bootstrap(fit, R = 100)
summary(fit) # with bootstrap confidence intervals
```


## How it works

survivalGPU is built on [PyTorch](https://pytorch.org) (with [KeOps](https://www.kernel-operations.io) additionally powering the WCE model). The R functions are thin wrappers around a Python implementation, called through the [reticulate](https://rstudio.github.io/reticulate/) package: this Python code is bundled with the R package, but it needs a Python environment with PyTorch installed. `vignette("installation", package = "survivalGPU")` explains how to set it up.

The WCE model needs the `pykeops` Python package, which is not available natively on Windows: there, `coxphGPU()` works, and `wceGPU()` can be used through the Windows Subsystem for Linux (WSL2).


## Vignettes

- `vignette("installation", package = "survivalGPU")`: install the package and its Python environment.
- `vignette("coxPH", package = "survivalGPU")`: Cox proportional hazards regression.
- `vignette("WCE", package = "survivalGPU")`: Weighted Cumulative Exposure models.


## References

[^cox1]: Andersen, P. and Gill, R. (1982). Cox's regression model for counting processes, a large sample study. Annals of Statistics 10, 1100-1120.
[^cox2]: Therneau, T., Grambsch, P., Modeling Survival Data: Extending the Cox Model. Springer-Verlag, 2000.
[^wce]: Sylvestre MP, Abrahamowicz M. Flexible modeling of the cumulative effects of time-dependent exposures on the hazard. Stat Med. 2009 Nov 30;28(27):3437-53. doi:10.1002/sim.3701
[^survival]: Therneau T (2026). A Package for Survival Analysis in R. R package version 3.8-9, <https://CRAN.R-project.org/package=survival>.
[^wcepkg]: Sylvestre M (2025). WCE: Weighted Cumulative Exposure Models. R package version 1.0.4, doi:10.32614/CRAN.package.WCE.
