| Title: | Fast and Scalable Implementations for Survival Models |
|---|---|
| Description: | Performs survival analysis on graphics processing units (GPUs) using Cox proportional hazards and weighted cumulative exposure (WCE) models, with support for bootstrap resampling and memory management. The Cox model is described in Cox (1972) <doi:10.1111/j.2517-6161.1972.tb00899.x> and the WCE model in Sylvestre and Abrahamowicz (2009) <doi:10.1002/sim.3701>. Computations are delegated to 'PyTorch' via 'reticulate'; the WCE model additionally requires 'PyKeOps', which is not available natively on Windows, but can be used there through the Windows Subsystem for Linux ('WSL'). |
| Authors: | Jean FEYDY [aut], Alexis van STRAATEN [aut], Antoine Poirot-Bourdain [aut, cre], Terry THERNEAU [ctb, cph] (Author of the 'survival' package, from which parts of the R code are adapted), Pierre SABATIER [ctb], Anne-Sophie JANNOT [ctb] |
| Maintainer: | Antoine Poirot-Bourdain <[email protected]> |
| License: | LGPL (>= 2.1) |
| Version: | 0.1.0 |
| Built: | 2026-11-18 00:20:03 UTC |
| Source: | https://github.com/cran/survivalGPU |
Fits Cox proportional hazards and weighted cumulative exposure (WCE) models on graphics processing units (GPUs), with bootstrap confidence intervals computed in batches.
To learn more about survivalGPU, start with vignette("survivalGPU").
use_cuda(): tells whether computations run on a GPU.
coxphGPU(): fits a Cox proportional hazards model.
wceGPU(): fits a weighted cumulative exposure model.
bootstrap(): adds bootstrap confidence intervals to a fitted model.
HR(): hazard ratio between two exposure histories, for a WCE model.
Maintainer: Antoine Poirot-Bourdain [email protected]
Authors:
Antoine Poirot-Bourdain [email protected]
Jean FEYDY [email protected]
Alexis van STRAATEN [email protected]
Other contributors:
Terry THERNEAU (Author of the 'survival' package, from which parts of the R code are adapted) [contributor, copyright holder]
Pierre SABATIER [contributor]
Anne-Sophie JANNOT [contributor]
Useful links:
Report bugs at https://github.com/jeanfeydy/survivalGPU/issues
Adds bootstrap confidence intervals to a model fitted by coxphGPU() or
wceGPU(). The model is refitted on R resamples of the patients, in
batches on the GPU.
bootstrap(object, ...) ## S3 method for class 'coxphGPU' bootstrap( object, R, batchsize = 0, init = TRUE, control, device = NULL, double_precision = TRUE, ... ) ## S3 method for class 'wceGPU' bootstrap( object, R, batchsize = 0, init = TRUE, device = NULL, double_precision = TRUE, ... )bootstrap(object, ...) ## S3 method for class 'coxphGPU' bootstrap( object, R, batchsize = 0, init = TRUE, control, device = NULL, double_precision = TRUE, ... ) ## S3 method for class 'wceGPU' bootstrap( object, R, batchsize = 0, init = TRUE, device = NULL, double_precision = TRUE, ... )
object |
A |
... |
Not used. |
R |
Number of bootstrap replicates. |
batchsize |
Number of bootstrap replicates processed at a time. |
init |
Starting coefficients of the refits. |
control |
( |
device |
Device on which the refits run ( |
double_precision |
Logical. |
For a coxphGPU model, object must have been fit with x = TRUE and
patient_id (coxphGPU(..., x = TRUE, patient_id = "id")). The bootstrap
resamples patients, not rows, so that all the rows of a patient (e.g. with
time-varying covariates) are kept together: patient_id tells which rows
belong to the same patient. The design matrix, the response and the
patient of each row are stored in the fit, so the bootstrap always uses
exactly the data the model was fitted on, including after subset = or
rows dropped for missing values.
For a wceGPU model, object must have been fit with x = TRUE
(wceGPU(..., x = TRUE)): the columns used by the model are stored in the
fit, and the bootstrap resamples them, so it always uses exactly the data
the model was fitted on. The spline-basis features are rebuilt from them
with the same knot configuration; the patient identifier is the id column
given at the fit.
If the model was fitted with several nknots candidates, the number of
knots is selected again in every bootstrap replicate (see
bootstrap.best.nknots), so that the confidence intervals account for the
uncertainty on that choice.
A copy of object with its bootstrap components updated; the point
estimates (coefficients, variance, residuals, ...) are unchanged, so
summary(), plot() and HR() show the bootstrap confidence intervals.
For a coxphGPU model: coef_bootstrap (one row per replicate) and
nbootstraps.
For a wceGPU model: bootstrap_beta.hat.covariates,
WCEmat_bootstrap, WCEmat_CI, coef_CI, bootstrap.best.nknots,
nbootstraps, is_bootstraps, and bootstrap_est/est_CI for a
single nknots value.
## Not run: library(survival) drugdata <- WCE::drugdata fit <- coxphGPU(Surv(Start, Stop, Event) ~ sex + age, data = drugdata, x = TRUE, patient_id = "Id") fit_boot <- bootstrap(fit, R = 1000, batchsize = 200) summary(fit_boot) ## End(Not run) ## Not run: drugdata <- WCE::drugdata fit <- wceGPU(data = drugdata, nknots = 1:3, cutoff = 90, id = "Id", event = "Event", start = "Start", stop = "Stop", expos = "dose", covariates = c("age", "sex"), x = TRUE) fit_boot <- bootstrap(fit, R = 500, batchsize = 100) summary(fit_boot) table(fit_boot$bootstrap.best.nknots) ## End(Not run)## Not run: library(survival) drugdata <- WCE::drugdata fit <- coxphGPU(Surv(Start, Stop, Event) ~ sex + age, data = drugdata, x = TRUE, patient_id = "Id") fit_boot <- bootstrap(fit, R = 1000, batchsize = 200) summary(fit_boot) ## End(Not run) ## Not run: drugdata <- WCE::drugdata fit <- wceGPU(data = drugdata, nknots = 1:3, cutoff = 90, id = "Id", event = "Event", start = "Start", stop = "Stop", expos = "dose", covariates = c("age", "sex"), x = TRUE) fit_boot <- bootstrap(fit, R = 500, batchsize = 100) summary(fit_boot) table(fit_boot$bootstrap.best.nknots) ## End(Not run)
Fits a Cox proportional hazards model on the GPU (or the CPU),
with the interface of survival::coxph(). Only point estimates are
computed: call bootstrap() on the result for bootstrap confidence
intervals, and inspect it with summary().
coxphGPU(formula, data, ties = c("efron", "breslow"), init, control, singular.ok = TRUE, model = FALSE, x = FALSE, y = TRUE, patient_id = NULL, ...) ## S3 method for class 'coxphGPU' summary(object, ..., conf.int = 0.95, scale = 1)coxphGPU(formula, data, ties = c("efron", "breslow"), init, control, singular.ok = TRUE, model = FALSE, x = FALSE, y = TRUE, patient_id = NULL, ...) ## S3 method for class 'coxphGPU' summary(object, ..., conf.int = 0.95, scale = 1)
formula |
A formula with a survival object (see |
data |
a data.frame in which to interpret the variables named in
the |
ties |
a character string specifying the method for tie handling. If there are no tied death times all the methods are equivalent. The Efron approximation is used as the default, it is more accurate when dealing with tied death times, and is as efficient computationally. (But see below for multi-state models.) The “exact partial likelihood” is equivalent to a conditional logistic model, and is appropriate when the times are a small set of discrete values. |
init |
vector of initial values of the iteration. Default initial value is zero for all variables. |
control |
Object of class |
singular.ok |
logical value indicating how to handle collinearity in the model matrix.
If |
model |
logical value: if |
x |
logical value: if |
y |
logical value: if |
patient_id |
Name of the column of |
... |
For |
object |
A |
conf.int |
level for computation of the confidence intervals. If set to FALSE no confidence intervals are printed |
scale |
vector of scale factors for the coefficients, defaults to 1. The printed coefficients, se, and confidence intervals will be associated with one scale unit. |
To compute bootstrap confidence intervals with bootstrap(), fit the model
with both x = TRUE, which stores the design matrix, and patient_id,
which stores the patient of each row used by the model. The bootstrap then
resamples exactly the data the model was fitted on.
coxphGPU() returns an object of class coxphGPU, with the
components of a survival::coxph() fit (coefficients, variance,
log-likelihood, ...). With patient_id, it also contains patient_id
(the column name) and patient_ids (the patient of each row used by the
model).
summary() returns an object of class summary.coxphGPU, with
confidence intervals for the hazard ratios from the normal approximation
and, if bootstrap() was called on the model, from the bootstrap. Its
main components are:
conf.int: matrix with one row per coefficient and the confidence
limits of exp(coef).
conf.int_bootstrap: the same limits, from the bootstrap.
logtest, sctest, waldtest: likelihood ratio, score and Wald tests
of the model.
concordance: concordance statistic and its standard error.
rsq: approximate of Nagelkerke (Biometrika, 1991).
Therneau T (2026). A Package for Survival Analysis in R. R
package version 3.8-9, https://CRAN.R-project.org/package=survival.
coxphGPU() follows the interface of its coxph(), calls it for the
model frame and the martingale residuals, and is tested against it.
Therneau TM, Grambsch PM (2000). Modeling Survival Data: Extending the Cox Model. Springer, New York.
survival::coxph(), bootstrap()
## Not run: library(survival) library(WCE) data(drugdata) ## Check CUDA drivers (if FALSE you use CPU) use_cuda() ## Cox Proportional Hazards point estimate; x = TRUE and patient_id are ## required if you plan to call bootstrap() on the result afterwards. fit <- coxphGPU(Surv(Start, Stop, Event) ~ sex + age, data = drugdata, x = TRUE, patient_id = "Id") ## Bootstrap-based inference, as a separate step fit_boot <- bootstrap(fit, R = 1000, batchsize = if (use_cuda()) 200 else 10) summary(fit_boot) ## End(Not run)## Not run: library(survival) library(WCE) data(drugdata) ## Check CUDA drivers (if FALSE you use CPU) use_cuda() ## Cox Proportional Hazards point estimate; x = TRUE and patient_id are ## required if you plan to call bootstrap() on the result afterwards. fit <- coxphGPU(Surv(Start, Stop, Event) ~ sex + age, data = drugdata, x = TRUE, patient_id = "Id") ## Bootstrap-based inference, as a separate step fit_boot <- bootstrap(fit, R = 1000, batchsize = if (use_cuda()) 200 else 10) summary(fit_boot) ## End(Not run)
Computes, from a model fitted by wceGPU(), the hazard ratio between two
exposure histories.
HR(object, vecnum, vecdenom, level = 0.95)HR(object, vecnum, vecdenom, level = 0.95)
object |
A |
vecnum |
Numeric vector: the exposure history of interest (numerator
of the HR), in reverse chronological order: the first value is the
exposure at the current time, the second the exposure one time unit
earlier, and so on. A vector longer than the |
vecdenom |
Numeric vector: the reference exposure history (denominator
of the HR), in the same order and with the same length rules as
|
level |
Level of the bootstrap confidence interval of the HR (default
|
A one-row matrix with the HR and, if bootstrap() was called on
object, the lower and upper limits of its bootstrap percentile
confidence interval.
## Not run: # Dataset drugdata <- WCE::drugdata # WCE model with bootstrap (example with 20 bootstraps) cutoff <- 90 wce_gpu <- wceGPU(data = drugdata, nknots = 1, cutoff = cutoff, id = "Id", event = "Event", start = "Start", stop = "Stop", expos = "dose", covariates = c("age", "sex"), constrained = FALSE, aic = FALSE, confint = 0.95, x = TRUE) wce_gpu_bootstrap <- bootstrap(wce_gpu, R = 20) # Exposed at a dose vs. unexposed exposed <- rep(1, cutoff) unexposed <- rep(0, cutoff) HR(wce_gpu_bootstrap, exposed, unexposed) ## End(Not run)## Not run: # Dataset drugdata <- WCE::drugdata # WCE model with bootstrap (example with 20 bootstraps) cutoff <- 90 wce_gpu <- wceGPU(data = drugdata, nknots = 1, cutoff = cutoff, id = "Id", event = "Event", start = "Start", stop = "Stop", expos = "dose", covariates = c("age", "sex"), constrained = FALSE, aic = FALSE, confint = 0.95, x = TRUE) wce_gpu_bootstrap <- bootstrap(wce_gpu, R = 20) # Exposed at a dose vs. unexposed exposed <- rep(1, cutoff) unexposed <- rep(0, cutoff) HR(wce_gpu_bootstrap, exposed, unexposed) ## End(Not run)
Computes fitted values and regression terms for a model fitted by
coxphGPU(), with survival::predict.coxph().
## S3 method for class 'coxphGPU' predict( object, newdata, type = c("lp", "risk", "expected", "terms", "survival"), se.fit = FALSE, na.action = na.pass, terms = names(object$assign), collapse, reference = c("strata", "sample", "zero"), ... )## S3 method for class 'coxphGPU' predict( object, newdata, type = c("lp", "risk", "expected", "terms", "survival"), se.fit = FALSE, na.action = na.pass, terms = names(object$assign), collapse, reference = c("strata", "sample", "zero"), ... )
object |
A |
newdata |
Optional new data at which to do predictions. If absent, predictions are for the data frame used in the original fit. When coxph has been called with a formula argument created in another context, i.e., coxph has been called within another function and the formula was passed as an argument to that function, there can be problems finding the data set. See the note below. |
type |
the type of predicted value.
Choices are the linear predictor ( |
se.fit |
if TRUE, pointwise standard errors are produced for the predictions. |
na.action |
applies only when the |
terms |
if type="terms", this argument can be used to specify which terms should be included; the default is all. |
collapse |
optional vector of subject identifiers. If specified, the output will contain one entry per subject rather than one entry per observation. |
reference |
reference for centering predictions, see details below |
... |
For future methods |
The predictions computed by survival::predict.coxph(): a numeric
vector with one element per observation, or a matrix with one column per
model term if type = "terms". If se.fit = TRUE, a list with
components fit (the predictions) and se.fit (their standard errors).
C Crowson, E Atkinson and T Therneau, Assessing calibration of prognostic risk scores, Stat Methods Med Res, 2016.
## Not run: library(survival) old_options <- options(na.action = na.exclude) # retain NA in predictions fit <- coxphGPU(Surv(time, status) ~ age + ph.ecog + strata(inst), lung) predict(fit, type = "lp") predict(fit, type = "expected") predict(fit, type = "risk", se.fit = TRUE) predict(fit, type = "terms", se.fit = TRUE) options(old_options) # restore the previous setting ## End(Not run)## Not run: library(survival) old_options <- options(na.action = na.exclude) # retain NA in predictions fit <- coxphGPU(Surv(time, status) ~ age + ph.ecog + strata(inst), lung) predict(fit, type = "lp") predict(fit, type = "expected") predict(fit, type = "risk", se.fit = TRUE) predict(fit, type = "terms", se.fit = TRUE) options(old_options) # restore the previous setting ## End(Not run)
Prints a model fitted by coxphGPU() in the same way as a
survival::coxph() fit. If bootstrap() was called on the model, a note
points to summary() for the bootstrap confidence intervals.
## S3 method for class 'coxphGPU' print(x, ..., digits = max(1L, getOption("digits") - 3L), signif.stars = FALSE)## S3 method for class 'coxphGPU' print(x, ..., digits = max(1L, getOption("digits") - 3L), signif.stars = FALSE)
x |
A |
... |
Not used. |
digits |
Number of significant digits to print. |
signif.stars |
Logical. If |
x, invisibly. Called for its side effect: printing the model.
Calculates martingale, deviance, score or Schoenfeld residuals for a Cox proportional hazards model.
## S3 method for class 'coxphGPU' residuals( object, ..., type = c("martingale", "deviance", "score", "schoenfeld", "dfbeta", "dfbetas", "scaledsch", "partial"), collapse = FALSE, weighted = (type %in% c("dfbeta", "dfbetas")) )## S3 method for class 'coxphGPU' residuals( object, ..., type = c("martingale", "deviance", "score", "schoenfeld", "dfbeta", "dfbetas", "scaledsch", "partial"), collapse = FALSE, weighted = (type %in% c("dfbeta", "dfbetas")) )
object |
an object inheriting from class |
... |
other unused arguments |
type |
character string indicating the type of residual desired.
Possible values are |
collapse |
either a logical (TRUE/FALSE), or a vector indicating which rows to collapse (sum) over. In time-dependent models more than one row data can pertain to a single individual or group. |
weighted |
if |
A vector or matrix of residuals, computed by
survival::residuals.coxph():
martingale and deviance residuals: a numeric vector with one element
per observation, or one per group if collapse is used;
score, dfbeta and dfbetas residuals: a matrix with one row per observation and one column per coefficient;
Schoenfeld and scaled Schoenfeld residuals: a matrix with one row per event and one column per coefficient;
partial residuals: a matrix with one row per observation and one column per model term.
T. Therneau, P. Grambsch, and T. Fleming. "Martingale based residuals for survival models", Biometrika, March 1990.
## Not run: library(survival) fit <- coxphGPU(Surv(start, stop, event) ~ age + surgery, data = heart) # Martingale residuals mresid <- resid(fit, collapse = heart$id) ## End(Not run)## Not run: library(survival) fit <- coxphGPU(Surv(start, stop, event) ~ age + surgery, data = heart) # Martingale residuals mresid <- resid(fit, collapse = heart$id) ## End(Not run)
Tells whether computations run on a GPU, i.e. whether 'PyTorch' detects CUDA drivers and a CUDA-capable GPU.
use_cuda()use_cuda()
A single logical value: TRUE if 'PyTorch' detects a CUDA-capable
GPU, in which case computations run on it by default; FALSE if they run
on the CPU. An error is raised if the Python backend cannot be loaded.
## Not run: use_cuda() ## End(Not run)## Not run: use_cuda() ## End(Not run)
Fits a weighted cumulative exposure (WCE) model on the GPU (or
the CPU). Only point estimates are computed: call bootstrap() on the
result for bootstrap confidence intervals, and inspect it with
summary() and plot().
wceGPU(data, nknots, cutoff, constrained = FALSE, aic = FALSE, id, event, start, stop, expos, covariates = NULL, confint = 0.95, x = FALSE, ...) ## S3 method for class 'wceGPU' summary(object, allres = FALSE, ...) ## S3 method for class 'wceGPU' plot(x, ..., hist.covariates = FALSE) ## S3 method for class 'wceGPU' confint(object, parm, level = 0.95, ..., digits = 3)wceGPU(data, nknots, cutoff, constrained = FALSE, aic = FALSE, id, event, start, stop, expos, covariates = NULL, confint = 0.95, x = FALSE, ...) ## S3 method for class 'wceGPU' summary(object, allres = FALSE, ...) ## S3 method for class 'wceGPU' plot(x, ..., hist.covariates = FALSE) ## S3 method for class 'wceGPU' confint(object, parm, level = 0.95, ..., digits = 3)
data |
Data frame in counting-process (long) format, with one row per subject and time unit. |
nknots |
Number of interior knots of the cubic spline that models the
weight function. With several values (e.g. |
cutoff |
Length, in time units, of the exposure history that affects
the hazard: the weight function is estimated for lags |
constrained |
Shape constraint on the weight function. |
aic |
Logical. Information criterion used to choose among the
|
id |
Name of the column of |
event |
Name of the column of |
start |
Name of the column of |
stop |
Name of the column of |
expos |
Name of the column of |
covariates |
Character vector with the names of the columns of |
confint |
Level of the bootstrap confidence intervals computed by
|
x |
For |
... |
For |
object |
A |
allres |
Logical. If |
hist.covariates |
Logical. If |
parm |
Covariates whose coefficients get a confidence interval, as numbers or names. Missing (default): all of them. |
level |
Confidence level of |
digits |
Number of significant digits of the levels in the column
names of |
At each time , the exposure enters the Cox model through
its weighted cumulative exposure over the last cutoff time units,
where is the exposure time units before .
The weight function is a cubic spline with nknots interior
knots. is therefore a linear combination of spline-weighted
exposure histories, which enter a Cox proportional hazards model as
time-dependent covariates, together with covariates. Their estimated
coefficients give , returned in WCEmat.
wceGPU() returns an object of class wceGPU: a list that describes
the selected model, i.e. the candidate in nknots that minimizes the
information criterion. Its main components are:
WCEmat: matrix with one row and cutoff columns, the estimated weight
function.
beta.hat.covariates, se.covariates: one-row matrices with the
estimated coefficients of the covariates and their standard errors.
est, SED: one-row matrices with the estimated spline coefficients
and their standard errors.
vcovmat: list holding the variance-covariance matrix of all the
coefficients (covariates, then spline coefficients).
knotsmat: one-row matrix with the knots of the spline basis.
loglik, info.criterion, nevents: partial log-likelihood,
information criterion (the BIC, or the AIC if aic = TRUE) and number of
events.
best.nknots: the selected number of interior knots. nknots.grid,
info.criterion.grid and loglik.grid give the candidates and the
information criterion and partial log-likelihood obtained for each.
data: with x = TRUE, the columns of data used by the model.
After bootstrap(), the object also contains:
WCEmat_bootstrap, bootstrap_beta.hat.covariates: matrices with one
row per bootstrap replicate, for the weight function and for the
coefficients of the covariates.
WCEmat_CI, coef_CI: two-row matrices with their lower and upper
percentile confidence limits, at level confint.
bootstrap.best.nknots: the number of knots selected in each replicate.
bootstrap_est, est_CI: the same for the spline coefficients, only
when a single nknots value is given.
summary() and plot() are called for their side effects (printing the
model, plotting the weight function) and return NULL invisibly.
confint() returns a matrix with one row per covariate and two columns:
the lower and upper confidence limits of its coefficient, based on the
normal approximation.
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
Sylvestre M (2025). WCE: Weighted Cumulative Exposure Models. R package
version 1.0.4. doi:10.32614/CRAN.package.WCE. The reference
implementation of the method: wceGPU() follows its interface, and its
results are tested against it.
Volinsky CT, Raftery AE (2000). Bayesian information criterion for censored survival models. Biometrics, 56(1), 256-262. doi:10.1111/j.0006-341X.2000.00256.x
## Not run: # Dataset drugdata <- WCE::drugdata # WCE model, point estimate only wce_gpu <- wceGPU(data = drugdata, nknots = 1, cutoff = 90, id = "Id", event = "Event", start = "Start", stop = "Stop", expos = "dose", covariates = c("age", "sex"), constrained = FALSE, aic = FALSE, confint = 0.95, x = TRUE) # Results wce_gpu summary(wce_gpu) # See estimated weight function plot(wce_gpu) # Bootstrap-based inference, as a separate step (example with 20 # replicates, but normally R > 500) wce_gpu_bootstrap <- bootstrap(wce_gpu, R = 20) # See confidence bands for the estimated weight function due to bootstrap plot(wce_gpu_bootstrap) # All estimated coefficients in bootstrap coef(wce_gpu_bootstrap) # Estimate a HR (Exposed at a dose vs. unexposed) exposed <- rep(1, 90) unexposed <- rep(0, 90) HR(wce_gpu_bootstrap, exposed, unexposed) ## End(Not run)## Not run: # Dataset drugdata <- WCE::drugdata # WCE model, point estimate only wce_gpu <- wceGPU(data = drugdata, nknots = 1, cutoff = 90, id = "Id", event = "Event", start = "Start", stop = "Stop", expos = "dose", covariates = c("age", "sex"), constrained = FALSE, aic = FALSE, confint = 0.95, x = TRUE) # Results wce_gpu summary(wce_gpu) # See estimated weight function plot(wce_gpu) # Bootstrap-based inference, as a separate step (example with 20 # replicates, but normally R > 500) wce_gpu_bootstrap <- bootstrap(wce_gpu, R = 20) # See confidence bands for the estimated weight function due to bootstrap plot(wce_gpu_bootstrap) # All estimated coefficients in bootstrap coef(wce_gpu_bootstrap) # Estimate a HR (Exposed at a dose vs. unexposed) exposed <- rep(1, 90) unexposed <- rep(0, 90) HR(wce_gpu_bootstrap, exposed, unexposed) ## End(Not run)