Package {SuperSurv}

Super Learner for conditional survival functions

Description

Orchestrates the cross-validation, metalearner optimization, and prediction for an ensemble of survival base learners.

Usage

SuperSurv(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  event.library,
  cens.library,
  id = NULL,
  verbose = FALSE,
  control = list(),
  cvControl = list(),
  obsWeights = NULL,
  metalearner = "brier",
  selection = "ensemble",
  nFolds = 10,
  parallel = FALSE
)

Arguments

Details

Extending the learner library. Custom base learners can be added by defining a wrapper function and passing its name in event.library or cens.library. A learner wrapper should accept time, event, X, newdata, new.times, obsWeights, id, and ..., and should return a list with pred, a numeric survival-probability matrix with nrow(newdata) rows and length(new.times) columns, and fit, the fitted object used for future prediction. If saved fits are needed, give fit a class and provide a corresponding predict.<class>() method that returns the same matrix shape. Wrapper outputs are validated before they enter the ensemble. Malformed prediction dimensions, non-finite values, values outside [0, 1], or a missing saved fit produce an error naming the learner and fitting stage.

Screening methods can also be supplied by name. A screener should accept the training inputs and return a logical vector aligned with the columns of X. Learner and screener names are resolved in the calling environment first, with package functions as a fallback. The resolved functions are reused across folds and full-data fitting, including parallel cross-validation. Thus, locally defined wrappers and grids can be used without assigning them globally. Prediction methods for custom fitted-object classes must still be available through normal S3 dispatch when predicting from saved fits. See vignette("extending-supersurv", package = "SuperSurv") for a practical custom learner and screener example.

Value

A list of class SuperSurv containing:

• call: The matched function call.

• event.predict: Matrix of in-sample cross-validated survival predictions.

• cens.predict: Matrix of in-sample cross-validated censoring predictions.

• eval.times: Numeric vector of prediction evaluation times.

• event.coef: Numeric vector of optimized ensemble weights for the event.

• cens.coef: Numeric vector of optimized ensemble weights for censoring.

• algorithm.diagnostics: Convergence, optimizer, and IPCW stabilization diagnostics from the iterative metalearner.

• event.library.predict: 3D array of cross-validated predictions from individual event learners.

• event.libraryNames: Data frame detailing the algorithms and screeners used.

• event.fitLibrary: List of the fitted base learner models (if saveFitLibrary = TRUE).

• times: The time grid used for evaluation.

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  new.times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = new.times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  fit
  event_weights(fit)
}

Control parameters for Cross-Validation in SuperSurv

Description

Control parameters for Cross-Validation in SuperSurv

Usage

SuperSurv.CV.control(
  V = 10L,
  stratifyCV = TRUE,
  shuffle = TRUE,
  validRows = NULL
)

Arguments

Value

A list of CV parameters.

Control parameters for the SuperSurv Ensemble

Description

Control parameters for the SuperSurv Ensemble

Usage

SuperSurv.control(
  max.SL.iter = 20,
  event.t.grid = NULL,
  cens.t.grid = NULL,
  saveFitLibrary = TRUE,
  initWeightAlg = "surv.coxph",
  initWeight = "censoring",
  tol = 1e-05,
  traceIter = FALSE,
  ipcw.floor = 1e-04,
  ipcw.cap = 100,
  logloss.eps = 1e-10,
  optimizer.tol = 1e-08,
  optimizer.maxit = 10000L,
  truncation.warn.fraction = 0.05
)

Arguments

Value

A list of control parameters.

Extract SuperSurv ensemble coefficients

Description

Returns the optimized convex-combination weights from a fitted SuperSurv object.

Usage

## S3 method for class 'SuperSurv'
coef(object, type = c("event", "censoring", "both"), ...)

Arguments

Value

For type = "event" or type = "censoring", a named numeric vector of ensemble weights. For type = "both", a list with elements event and censoring.

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  new.times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = new.times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  coef(fit)
  coef(fit, type = "both")
}

Create a Tuning Grid of Survival Learners

Description

Dynamically generates custom wrapper functions for a specified base learner across a grid of hyperparameters.

Usage

create_grid(base_learner, grid_params)

Arguments

Details

Generated functions are assigned to the calling environment. The base learner is resolved there (with package functions as a fallback) when the grid is created and retained by each generated function. Local base learners and grids can therefore be used inside a function that calls SuperSurv(), without modifying the global environment.

Value

A character vector of class "SuperSurv_grid" containing the newly generated function names.

Estimate an Adjusted Marginal RMST Contrast

Description

Computes a covariate-adjusted marginal contrast on the restricted mean survival time (RMST) scale using standardization (g-computation) based on a fitted SuperSurv model.

Usage

estimate_marginal_rmst(
  fit,
  data,
  trt_col,
  times,
  tau,
  inference = FALSE,
  B = 200,
  seed = NULL,
  ci_level = 0.95
)

Arguments

Details

For a binary grouping variable trt_col, the function predicts counterfactual survival curves under A = 1 and A = 0 for every individual in the supplied dataset, integrates each curve up to the restriction time tau, and averages the resulting individual-level RMST differences. The resulting contrast is generally interpreted as an adjusted marginal contrast. When trt_col corresponds to a manipulable intervention and additional identification assumptions hold, the same standardized procedure may also support a causal interpretation.

The function uses the empirical distribution of the observed covariates in data as the standardization distribution. RMST is evaluated numerically from the predicted survival matrix using a left Riemann sum over the supplied grid times.

The returned contrast is a model-based point estimate. Formal uncertainty quantification would need to account for nuisance estimation, tuning, cross-validation, learner fitting, and ensemble-weight estimation, for example through a validated full-pipeline refitting procedure.

Value

A list containing:

• ATE_RMST: The estimated adjusted marginal RMST contrast \widehat{\Delta}_{RMST}(\tau).

• mean_RMST_Treated: The average predicted RMST under A = 1.

• mean_RMST_Control: The average predicted RMST under A = 0.

• tau: The restriction horizon used for integration.

• patient_rmst_treated: Vector of individual-level predicted RMST values under A = 1.

• patient_rmst_control: Vector of individual-level predicted RMST values under A = 0.

• patient_delta_rmst: Vector of individual-level predicted RMST contrasts.

• inference: Always FALSE; retained for compatibility.

Examples

## Not run: 
data("metabric", package = "SuperSurv")
x_cols <- grep("^x", names(metabric), value = TRUE)
X <- metabric[, x_cols]
new.times <- seq(10, 150, by = 10)

fit <- SuperSurv(
  time = metabric$duration,
  event = metabric$event,
  X = X,
  newdata = X,
  new.times = new.times,
  event.library = c("surv.coxph", "surv.rfsrc"),
  cens.library = c("surv.coxph"),
  control = list(saveFitLibrary = TRUE),
  nFolds = 3
)

rmst_res <- estimate_marginal_rmst(
  fit = fit,
  data = metabric,
  trt_col = "x4",
  times = new.times,
  tau = 100
)

rmst_res$ATE_RMST

## End(Not run)

Evaluate survival predictions across models and times

Description

Computes a common set of numerical benchmark results for a fitted SuperSurv object or supported standalone learner. The censoring distribution used by the Brier score and time-dependent AUC is estimated marginally by Kaplan-Meier. For conditional censoring models, resampling, inference, or formal model comparisons, use a specialist evaluator such as riskRegression::Score().

Usage

eval_benchmark(
  object,
  newdata,
  time,
  event,
  eval_times,
  risk_time = stats::median(eval_times),
  verbose = FALSE
)

Arguments

Value

A list of class "SuperSurv_benchmark" containing summary, a model-level table; by_time, a time-specific table; and the prediction grid and risk horizon.

IPCW Brier Score and Integrated Brier Score (IBS)

Description

Calculates the Inverse Probability of Censoring Weighted (IPCW) Brier Score over a grid of times, and computes the Integrated Brier Score (IBS) using trapezoidal integration.

Usage

eval_brier(
  time,
  event,
  S_mat,
  times,
  tmin = min(times),
  tmax = max(times),
  ipcw_floor = 1e-06
)

Arguments

Value

A list containing:

• brier_scores: A numeric vector of Brier scores at each time point.

• ibs: The Integrated Brier Score over the range ⁠\code{tmin}, \code{tmax}⁠.

• times: The time grid used.

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:40, ]
x_cols <- grep("^x", names(dat))[1:3]
X <- dat[, x_cols, drop = FALSE]
newX <- X[1:10, , drop = FALSE]
times <- seq(50, 150, by = 50)

fit <- surv.coxph(
  time = dat$duration,
  event = dat$event,
  X = X,
  newdata = newX,
  new.times = times,
  obsWeights = rep(1, nrow(dat)),
  id = NULL
)

eval_brier(
  time = dat$duration[1:10],
  event = dat$event[1:10],
  S_mat = fit[["pred"]],
  times = times
)

Calculate Concordance Index (Harrell's or Uno's)

Description

Calculate Concordance Index (Harrell's or Uno's)

Usage

eval_cindex(time, event, S_mat, times, eval_time, method = "uno")

Arguments

Value

A numeric value representing the chosen C-index.

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:40, ]
x_cols <- grep("^x", names(dat))[1:3]
X <- dat[, x_cols, drop = FALSE]
newX <- X[1:10, , drop = FALSE]
times <- seq(50, 150, by = 50)

fit <- surv.coxph(
  time = dat$duration,
  event = dat$event,
  X = X,
  newdata = newX,
  new.times = times,
  obsWeights = rep(1, nrow(dat)),
  id = NULL
)

eval_cindex(
  time = dat$duration[1:10],
  event = dat$event[1:10],
  S_mat = fit[["pred"]],
  times = times,
  eval_time = 100,
  method = "uno"
)

IPCW Log-Loss and Integrated IPCW Log-Loss

Description

Evaluates the two-term inverse-probability-of-censoring weighted log-loss. By default, censoring survival is estimated using marginal reverse Kaplan-Meier. Conditional or externally estimated censoring survival values can instead be supplied explicitly. Probability clipping is applied only inside logarithms.

Usage

eval_logloss(
  time,
  event,
  S_mat,
  times,
  tmin = min(times),
  tmax = max(times),
  ipcw_floor = 1e-06,
  eps = 1e-10,
  ipcw_cap = Inf,
  G_T_left = NULL,
  G_times = NULL
)

Arguments

Value

A list containing logloss_scores, integrated_logloss, times, and diagnostics. Diagnostics report the effective denominator threshold, intervention counts, weight quantiles, effective sample sizes, and the fraction of weighted loss contributed by capped rows, separately for failure and survivor terms.

Evaluate SuperSurv predictions on test data

Description

Computes the integrated Brier score (IBS), Uno C-index, and integrated area under the curve (iAUC) for the SuperSurv ensemble and all individual base learners.

Usage

eval_summary(
  object,
  newdata,
  time,
  event,
  eval_times,
  risk_time = stats::median(eval_times),
  verbose = FALSE
)

Arguments

Value

A data frame of integrated benchmark metrics for the ensemble and base learners. Use eval_benchmark() to also obtain time-specific numerical results.

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:80, ]
x_cols <- grep("^x", names(dat))[1:3]

fit <- SuperSurv(
  time = dat$duration,
  event = dat$event,
  X = dat[, x_cols, drop = FALSE],
  new.times = seq(50, 200, by = 50),
  event.library = c("surv.coxph", "surv.km"),
  cens.library = c("surv.coxph", "surv.km")
)

res <- eval_summary(
  object = fit,
  newdata = dat[, x_cols, drop = FALSE],
  time = dat$duration,
  event = dat$event,
  eval_times = seq(50, 200, by = 50)
)

res

Time-Dependent AUC and Integrated AUC

Description

Evaluates the cumulative/dynamic time-dependent AUC and integrated AUC (iAUC) using inverse probability of censoring weighting (IPCW).

Usage

eval_timeROC(time, event, S_mat, times)

Arguments

Value

A list containing the AUC_curve at each time point, the times, and the integrated AUC iAUC.

Examples

 data("metabric", package = "SuperSurv")
 dat <- metabric[1:40, ]
 x_cols <- grep("^x", names(dat))[1:3]
 X <- dat[, x_cols, drop = FALSE]
 newX <- X[1:10, , drop = FALSE]
 times <- seq(50, 150, by = 50)

 fit <- surv.coxph(
   time = dat$duration,
   event = dat$event,
   X = X,
   newdata = newX,
   new.times = times,
   obsWeights = rep(1, nrow(dat)),
   id = NULL
 )

 eval_timeROC(
   time = dat$duration[1:10],
   event = dat$event[1:10],
   S_mat = fit[["pred"]],
   times = times
 )

Access SuperSurv prediction evaluation times

Description

Returns the time grid used for the fitted SuperSurv predictions.

Usage

eval_times(object, ...)

## Default S3 method:
eval_times(object, ...)

## S3 method for class 'SuperSurv'
eval_times(object, ...)

Arguments

Value

A numeric vector of prediction evaluation times.

Access SuperSurv ensemble weights

Description

Extracts the fitted event or censoring ensemble weights from a SuperSurv object.

Usage

event_weights(object, ...)

## Default S3 method:
event_weights(object, ...)

## S3 method for class 'SuperSurv'
event_weights(object, ...)

censor_weights(object, ...)

## Default S3 method:
censor_weights(object, ...)

## S3 method for class 'SuperSurv'
censor_weights(object, ...)

Arguments

Value

A named numeric vector of ensemble weights.

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  new.times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = new.times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  event_weights(fit)
  censor_weights(fit)
}

Explain Predictions with Global SHAP (Kernel SHAP)

Description

Explain Predictions with Global SHAP (Kernel SHAP)

Usage

explain_kernel(
  model,
  X_explain,
  X_background,
  nsim = 20,
  only_best = FALSE,
  verbose = FALSE,
  eval_time = NULL
)

Arguments

Details

The explained function uses the stored survival-prediction methods, including screening and calibration. All positive ensemble weights are used; small weights are not discarded. This replaces the earlier mixture of native learner scores, so SHAP values from earlier releases are not comparable. The background sample defines marginal, not conditional or causal, SHAP values.

Value

A data.frame of class c("explain", "data.frame") containing the calculated SHAP values. The columns correspond to the covariates in X_explain. Attributes include baseline, predictions, eval_time, target = "event_probability", and backend convergence information.

Examples

if (FALSE) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  new.times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = new.times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  shap_values <- explain_kernel(
    model = fit,
    X_explain = X[1:10, , drop = FALSE],
    X_background = X[11:40, , drop = FALSE],
    nsim = 5, eval_time = 100
  )

  dim(shap_values)
}

Create a Time-Dependent Survex Explainer

Description

Bridges a fitted SuperSurv ensemble or a single base learner to the survex package for Time-Dependent SHAP and Model Parts.

Usage

explain_survex(model, data, y, times, label = NULL)

Arguments

Value

An explainer object of class survex_explainer created by explain_survival, which can be passed to DALEX and survex functions for further model diagnostics and plotting.

Examples

if (requireNamespace("survex", quietly = TRUE) &&
    requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  times <- seq(20, 120, by = 20)
  y <- survival::Surv(dat$duration, dat$event)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  explainer <- explain_survex(
    model = fit,
    data = X,
    y = y,
    times = times,
    label = "SuperSurv_demo"
  )

  class(explainer)
}

Calculate Restricted Mean Survival Time (RMST)

Description

Calculate Restricted Mean Survival Time (RMST)

Usage

get_rmst(surv_matrix, times, tau)

Arguments

Value

A vector of RMST values for each patient

Access SuperSurv learner names

Description

Returns the fitted learner names from a SuperSurv object.

Usage

learner_names(object, ...)

## Default S3 method:
learner_names(object, ...)

## S3 method for class 'SuperSurv'
learner_names(object, type = c("event", "censoring", "both"), ...)

Arguments

Value

For type = "event" or type = "censoring", a character vector of learner names. For type = "both", a list with elements event and censoring.

List Available Wrappers and Screeners in SuperSurv

Description

This function prints all built-in prediction algorithms and feature screening algorithms available in the SuperSurv package.

Usage

list_wrappers(what = "both")

Arguments

Value

An invisible character vector containing the requested function names.

Examples

list_wrappers()

METABRIC Breast Cancer Dataset

Description

A subset of the Molecular Taxonomy of Breast Cancer International Consortium (METABRIC) dataset to demonstrate the SuperSurv package. 9 Covariates: 4 gene indicators (MKI67, EGFR, PGR, and ERBB2) and 5 clinical features (age at diagnosis, and indicators for hormone treatment, radiotherapy, and chemotherapy)

Usage

metabric

Format

A data frame with the clinical and genomic variables:

duration

Survival time.

event

Event indicator (1 = event, 0 = censored).

x0

Feature x0.

x1

Feature x1.

x2

Feature x2.

x3

Feature x3.

x4

Feature x4.

x5

Feature x5.

x6

Feature x6.

x7

Feature x7.

x8

Feature x8.

Beeswarm Summary Plot for SuperSurv SHAP

Description

Beeswarm Summary Plot for SuperSurv SHAP

Usage

plot_beeswarm(shap_values, data, top_n = 10)

Arguments

Value

A ggplot object visualizing the SHAP values.

Examples

if (FALSE) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  new.times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = new.times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  shap_values <- explain_kernel(
    model = fit,
    X_explain = X[1:20, , drop = FALSE],
    X_background = X[21:50, , drop = FALSE],
    nsim = 5, eval_time = 100
  )

  plot_beeswarm(
    shap_values = shap_values,
    data = X[1:20, , drop = FALSE],
    top_n = 5
  )
}

Plot Longitudinal Benchmark Metrics

Description

Generates time-dependent performance curves comparing the SuperSurv ensemble against its base learners, or evaluates a single standalone learner.

Usage

plot_benchmark(
  object,
  newdata,
  time,
  event,
  eval_times,
  metrics = c("brier", "auc", "cindex"),
  verbose = FALSE
)

Arguments

Value

A combined patchwork object when patchwork is installed, a single ggplot when one metric is selected, or a named list of ggplots when multiple metrics are requested without patchwork.

Examples

if (requireNamespace("ranger", quietly = TRUE) &&
    requireNamespace("ggplot2", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:120, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  eval_times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = eval_times,
    event.library = c("surv.coxph", "surv.ranger"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  plot_benchmark(
    object = fit,
    newdata = X,
    time = dat$duration,
    event = dat$event,
    eval_times = eval_times,
    metrics = c("brier")
  )
}

Plot Survival Calibration Curve

Description

Plot Survival Calibration Curve

Usage

plot_calibration(object, newdata, time, event, eval_time, bins = 5)

Arguments

Value

A ggplot object.

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:120, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  eval_times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = eval_times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  plot_calibration(
    object = fit,
    newdata = X,
    time = dat$duration,
    event = dat$event,
    eval_time = 100,
    bins = 4
  )
}

Plot SHAP Dependence for SuperSurv

Description

Plot SHAP Dependence for SuperSurv

Usage

plot_dependence(shap_values, data, feature_name, title = NULL)

Arguments

Value

A ggplot object visualizing the SHAP values.

Examples

if (FALSE) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  new.times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = new.times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  shap_values <- explain_kernel(
    model = fit,
    X_explain = X[1:20, , drop = FALSE],
    X_background = X[21:50, , drop = FALSE],
    nsim = 5, eval_time = 100
  )

  plot_dependence(
    shap_values = shap_values,
    data = X[1:20, , drop = FALSE],
    feature_name = colnames(X)[1]
  )
}

Plot Global Feature Importance for SuperSurv

Description

Plot Global Feature Importance for SuperSurv

Usage

plot_global_importance(
  shap_values,
  title = "SuperSurv: Ensemble Feature Importance",
  top_n = 10
)

Arguments

Value

A ggplot object visualizing the SHAP values.

Examples

if (FALSE) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  new.times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = new.times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  shap_values <- explain_kernel(
    model = fit,
    X_explain = X[1:10, , drop = FALSE],
    X_background = X[11:40, , drop = FALSE],
    nsim = 5, eval_time = 100
  )

  plot_global_importance(shap_values, top_n = 5)
}

Plot Adjusted Marginal RMST Contrast Over Time

Description

Generates a curve showing how the adjusted marginal restricted mean survival time (RMST) contrast evolves across a sequence of restriction times.

Usage

plot_marginal_rmst_curve(
  fit,
  data,
  trt_col,
  times,
  tau_seq,
  inference = FALSE,
  B = 200,
  seed = NULL,
  ci_level = 0.95
)

Arguments

Value

A ggplot object visualizing the adjusted marginal RMST contrast curve.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
data("metabric", package = "SuperSurv")
dat <- metabric[1:80, ]
x_cols <- grep("^x", names(dat), value = TRUE)[1:5]
X <- dat[, x_cols, drop = FALSE]
new.times <- seq(20, 120, by = 20)

fit <- SuperSurv(
  time = dat$duration,
  event = dat$event,
  X = X,
  newdata = X,
  new.times = new.times,
  event.library = c("surv.coxph"),
  cens.library = c("surv.coxph"),
  control = list(saveFitLibrary = TRUE)
)

tau_grid <- seq(40, 120, by = 20)
plot_marginal_rmst_curve(
  fit = fit,
  data = dat,
  trt_col = "x4",
  times = new.times,
  tau_seq = tau_grid
)
}

Waterfall Plot for an Individual Patient

Description

Waterfall Plot for an Individual Patient

Usage

plot_patient_waterfall(shap_values, patient_index = 1, top_n = 10)

Arguments

Value

A ggplot object visualizing the SHAP values.

Examples

if (FALSE) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  new.times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = new.times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  shap_values <- explain_kernel(
    model = fit,
    X_explain = X[1:10, , drop = FALSE],
    X_background = X[11:40, , drop = FALSE],
    nsim = 5, eval_time = 100
  )

  plot_patient_waterfall(
    shap_values = shap_values,
    patient_index = 1,
    top_n = 5
  )
}

Plot Predicted Survival Curves

Description

Plot Predicted Survival Curves

Usage

plot_predict(preds, eval_times, patient_idx = 1)

Arguments

Value

A ggplot object.

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:120, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  eval_times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = eval_times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  preds <- predict(fit, newdata = X, new.times = eval_times, type = "event")

  plot_predict(
    preds = preds,
    eval_times = eval_times,
    patient_idx = c(1, 2)
  )
}

Plot Predicted RMST vs. Observed Survival Times

Description

Evaluates the calibration of the causal RMST estimator by plotting the model's predicted RMST for each patient against their actual observed follow-up time.

Usage

plot_rmst_vs_obs(fit, data, time_col, event_col, times, tau)

Arguments

Value

A ggplot object comparing predicted RMST to observed outcomes.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
data("metabric", package = "SuperSurv")
dat <- metabric[1:80, ]
x_cols <- grep("^x", names(dat))[1:5]
X <- dat[, x_cols, drop = FALSE]
new.times <- seq(20, 120, by = 20)

fit <- SuperSurv(
  time = dat$duration,
  event = dat$event,
  X = X,
  newdata = X,
  new.times = new.times,
  event.library = c("surv.coxph"),
  cens.library = c("surv.coxph"),
  control = list(saveFitLibrary = TRUE)
)

plot_rmst_vs_obs(
  fit = fit,
  data = dat,
  time_col = "duration",
  event_col = "event",
  times = new.times,
  tau = 100
)
}

Survival Probability Heatmap

Description

Survival Probability Heatmap

Usage

plot_survival_heatmap(object, newdata, times)

Arguments

Value

A ggplot object visualizing the SHAP values.

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  plot_survival_heatmap(
    object = fit,
    newdata = X[1:20, , drop = FALSE],
    times = times
  )
}

Predict method for SuperSurv fits

Description

Obtains predicted survival probabilities from a fitted SuperSurv ensemble.

Usage

## S3 method for class 'SuperSurv'
predict(
  object,
  newdata,
  new.times,
  type = c("both", "event", "censoring"),
  onlySL = FALSE,
  threshold = 1e-04,
  ...
)

Arguments

Value

If type = "event" or type = "censoring", a numeric matrix with rows corresponding to observations and columns corresponding to new.times. If type = "both", a list containing:

• event.predict: A numeric matrix of final event survival predictions.

• event.library.predict: A 3D numeric array of event learner predictions.

• cens.predict: A numeric matrix of final censoring survival predictions.

• cens.library.predict: A 3D numeric array of censoring learner predictions.

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:10, , drop = FALSE]
  new.times <- seq(20, 120, by = 20)

  fit <- SuperSurv(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = X,
    new.times = new.times,
    event.library = c("surv.coxph", "surv.ridge"),
    cens.library = c("surv.coxph"),
    control = list(saveFitLibrary = TRUE)
  )

  pred_event <- predict(
    object = fit,
    newdata = newX,
    new.times = new.times,
    type = "event"
  )

  dim(pred_event)
}

Print a SuperSurv fit

Description

Prints a concise description of a fitted SuperSurv object.

Usage

## S3 method for class 'SuperSurv'
print(x, digits = max(3L, getOption("digits") - 3L), ...)

Arguments

Value

The input object x, invisibly.

Keep All Variables Screener

Description

Keep All Variables Screener

Usage

screen.all(X, ...)

Arguments

Value

A logical vector of the same length as the number of columns in X, indicating which variables passed the screening algorithm (TRUE to keep, FALSE to drop).

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:20, ]
x_cols <- grep("^x", names(dat))[1:5]
X <- dat[, x_cols, drop = FALSE]

screen.all(X)

Elastic Net Screening Algorithm

Description

This screening algorithm uses cv.glmnet to select covariates. Unlike LASSO (alpha = 1), which drops correlated features, Elastic Net (alpha = 0.5 by default) shrinks correlated groups of features together, making it ideal for selecting entire biological pathways.

Usage

screen.elasticnet(
  time,
  event,
  X,
  obsWeights = NULL,
  alpha = 0.5,
  minscreen = 2,
  nfolds = 10,
  nlambda = 100,
  ...
)

Arguments

Value

A logical vector of the same length as the number of columns in X, indicating which variables passed the screening algorithm (TRUE to keep, FALSE to drop).

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:40, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]

  screen.elasticnet(
    time = dat$duration,
    event = dat$event,
    X = X,
    alpha = 0.5,
    minscreen = 2,
    nfolds = 3,
    nlambda = 20
  )
}

GLMNET (Lasso) Screening

Description

GLMNET (Lasso) Screening

Usage

screen.glmnet(
  time,
  event,
  X,
  obsWeights = NULL,
  alpha = 1,
  minscreen = 2,
  nfolds = 10,
  nlambda = 100,
  ...
)

Arguments

Value

A logical vector of the same length as the number of columns in X, indicating which variables passed the screening algorithm (TRUE to keep, FALSE to drop).

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:40, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]

  screen.glmnet(
    time = dat$duration,
    event = dat$event,
    X = X,
    alpha = 1,
    minscreen = 2,
    nfolds = 3,
    nlambda = 20
  )
}

Marginal Cox Regression Screening

Description

Marginal Cox Regression Screening

Usage

screen.marg(time, event, X, obsWeights = NULL, minscreen = 2, min.p = 0.1, ...)

Arguments

Value

A logical vector of the same length as the number of columns in X, indicating which variables passed the screening algorithm (TRUE to keep, FALSE to drop).

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:40, ]
x_cols <- grep("^x", names(dat))[1:5]
X <- dat[, x_cols, drop = FALSE]

screen.marg(
  time = dat$duration,
  event = dat$event,
  X = X,
  minscreen = 2,
  min.p = 0.2
)

Random Survival Forest Screening Algorithm

Description

This screening algorithm uses the randomForestSRC package to select covariates based on their Variable Importance (VIMP). It grows a fast forest and retains features with a VIMP greater than zero.

Usage

screen.rfsrc(
  time,
  event,
  X,
  obsWeights = NULL,
  minscreen = 2,
  ntree = 100,
  ...
)

Arguments

Value

A logical vector of the same length as the number of columns in X, indicating which variables passed the screening algorithm (TRUE to keep, FALSE to drop).

Examples

if (requireNamespace("randomForestSRC", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:40, ]
  x_cols <- grep("^x", names(dat))[1:5]
  X <- dat[, x_cols, drop = FALSE]

  screen.rfsrc(
    time = dat$duration,
    event = dat$event,
    X = X,
    minscreen = 2,
    ntree = 10
  )
}

High Variance Screening Algorithm (Unsupervised)

Description

An unsupervised screening algorithm that filters out low-variance features. This is particularly useful for high-dimensional genomic or transcriptomic data where many features remain relatively constant across all observations.

Usage

screen.var(
  time,
  event,
  X,
  obsWeights = NULL,
  keep_fraction = 0.5,
  minscreen = 2,
  ...
)

Arguments

Value

A logical vector of the same length as the number of columns in X, indicating which variables passed the screening algorithm (TRUE to keep, FALSE to drop).

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:40, ]
x_cols <- grep("^x", names(dat))[1:6]
X <- dat[, x_cols, drop = FALSE]

screen.var(
  time = dat$duration,
  event = dat$event,
  X = X,
  keep_fraction = 0.5,
  minscreen = 2
)

Access variables selected by SuperSurv screeners

Description

Returns the variables retained by a screening step for one or more fitted event or censoring learners.

Usage

selected_variables(object, ...)

## Default S3 method:
selected_variables(object, ...)

## S3 method for class 'SuperSurv'
selected_variables(object, type = c("event", "censoring"), learner = NULL, ...)

Arguments

Value

A named list of character vectors, or a single character vector when learner has length one.

Summarize a SuperSurv fit

Description

Summarizes the fitted event and censoring ensembles, including learner names, ensemble weights, cross-validated risks, error flags, prediction dimensions, and recorded timing information.

Usage

## S3 method for class 'SuperSurv'
summary(object, ...)

## S3 method for class 'summary.SuperSurv'
print(x, digits = max(3L, getOption("digits") - 3L), ...)

Arguments

Value

An object of class "summary.SuperSurv", a list containing the matched call, selection mode, event and censoring learner summaries, prediction dimensions, and timing information.

Wrapper for AORSF (Oblique Random Survival Forest)

Description

Final Production Wrapper for AORSF (Tunable & Robust).

Usage

surv.aorsf(
  time,
  event,
  X,
  newdata,
  new.times,
  obsWeights,
  id,
  n_tree = 500,
  leaf_min_events = 5,
  mtry = NULL,
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

if (requireNamespace("aorsf", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:30, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.aorsf(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times,
    obsWeights = rep(1, nrow(dat)),
    id = NULL,
    n_tree = 10,
    leaf_min_events = 2
  )

  dim(fit[["pred"]])
}

Wrapper for BART (Bayesian Additive Regression Trees)

Description

Final Production Wrapper for BART (Tunable & Robust). Uses the mc.surv.bart function. Automatically reshapes the flat output vector into a survival matrix and interpolates the predictions to the requested new.times.

Usage

surv.bart(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  obsWeights = NULL,
  id = NULL,
  ntree = 10,
  ndpost = 30,
  nskip = 10,
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

## Not run: 
if (.Platform$OS.type != "windows" &&
  requireNamespace("BART", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:20, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.bart(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times,
    ntree = 3,
    ndpost = 5,
    nskip = 5
  )

  dim(fit[["pred"]])
}

## End(Not run)

Wrapper function for Component-Wise Boosting (CoxBoost)

Description

Final Production Wrapper for CoxBoost (Tunable & Robust). Estimates a Cox model via component-wise likelihood based boosting.

Usage

surv.coxboost(
  time,
  event,
  X,
  newdata,
  new.times,
  obsWeights,
  id,
  stepno = 100,
  penalty = 100,
  ties = c("breslow", "efron"),
  survival_transform = c("exponential", "product_limit"),
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

if (requireNamespace("CoxBoost", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:30, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.coxboost(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times,
    obsWeights = rep(1, nrow(dat)),
    id = NULL,
    stepno = 10,
    penalty = 50
  )

  dim(fit[["pred"]])
}

Wrapper for standard Cox Proportional Hazards

Description

Final Production Wrapper for CoxPH. Uses partial maximum likelihood and the Breslow estimator.

Usage

surv.coxph(time, event, X, newdata, new.times, obsWeights, id, ...)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:30, ]
x_cols <- grep("^x", names(dat))[1:3]
X <- dat[, x_cols, drop = FALSE]
newX <- X[1:5, , drop = FALSE]
times <- seq(50, 150, by = 50)

fit <- surv.coxph(
  time = dat$duration,
  event = dat$event,
  X = X,
  newdata = newX,
  new.times = times,
  obsWeights = rep(1, nrow(dat)),
  id = NULL
)

dim(fit[["pred"]])

Experimental Cox-Time Neural Survival Learner

Description

Fits a neural Cox-Time model allowing time-dependent covariate effects through survivalmodels::coxtime(). This optional adapter requires Python torch, torchtuples, and pycox and supports only uniform observation weights.

Usage

surv.coxtime(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  obsWeights = NULL,
  id = NULL,
  num_nodes = c(32L, 32L),
  activation = "relu",
  batch_norm = TRUE,
  dropout = NULL,
  epochs = 100L,
  batch_size = 128L,
  device = NULL,
  verbose = FALSE,
  seed = 1L,
  standardize_time = TRUE,
  ...
)

Arguments

Details

Native survival curves are evaluated as right-continuous steps on the backend's time grid, using survival one before the first grid point and the final available value beyond the last point. This is not a claim of reliable extrapolation beyond observed follow-up. Python-backed fitted objects are intended for reuse within the active R/Python session; plain saveRDS() is not a portable persistence format for Python objects.

Value

A list with numeric survival matrix pred and fitted object fit.

Examples

if (interactive() && requireNamespace("survivalmodels", quietly = TRUE) &&
    requireNamespace("reticulate", quietly = TRUE) &&
    reticulate::py_module_available("pycox")) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:60, ]
  X <- dat[, "x1", drop = FALSE]
  fit <- surv.coxtime(dat$duration, dat$event, X,
                      X[1:3, , drop = FALSE], c(50, 100),
                      epochs = 2, batch_norm = FALSE, device = "cpu")
  dim(fit$pred)
}

Experimental DeepHit Learner

Description

Fits a single-event discrete-time DeepHit neural network through survivalmodels::deephit(). This optional adapter requires a Python environment containing torch, torchtuples, and pycox and currently supports only uniform observation weights.

Usage

surv.deephit(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  obsWeights = NULL,
  id = NULL,
  num_nodes = c(32L, 32L),
  activation = "relu",
  batch_norm = TRUE,
  dropout = NULL,
  epochs = 100L,
  batch_size = 128L,
  device = NULL,
  verbose = FALSE,
  seed = 1L,
  cuts = 20L,
  cutpoints = NULL,
  scheme = c("equidistant", "quantiles"),
  mod_alpha = 0.2,
  sigma = 0.1,
  ...
)

Arguments

Details

Fitted Python objects can be reused in the active R/Python session. Plain saveRDS() is not a portable persistence format for these objects. Native survival curves are mapped to requested times as right-continuous steps; see surv.coxtime() for the boundary convention.

Value

A list with numeric matrix pred and fitted object fit.

Examples

if (interactive() && requireNamespace("survivalmodels", quietly = TRUE) &&
    requireNamespace("reticulate", quietly = TRUE) &&
    reticulate::py_module_available("pycox")) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:60, ]
  X <- dat[, grep("^x", names(dat))[1:3], drop = FALSE]
  fit <- surv.deephit(
    dat$duration, dat$event, X, X[1:4, , drop = FALSE],
    c(50, 100), cuts = 10, epochs = 2, seed = 1
  )
  dim(fit$pred)
}

Experimental DeepSurv Learner

Description

Fits a Cox partial-likelihood neural network through survivalmodels::deepsurv(). This optional adapter requires a Python environment containing torch, torchtuples, and pycox and currently supports only uniform observation weights.

Usage

surv.deepsurv(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  obsWeights = NULL,
  id = NULL,
  num_nodes = c(32L, 32L),
  activation = "relu",
  batch_norm = TRUE,
  dropout = NULL,
  epochs = 100L,
  batch_size = 128L,
  device = NULL,
  verbose = FALSE,
  seed = 1L,
  ...
)

Arguments

Details

Fitted Python objects can be reused in the active R/Python session. Plain saveRDS() is not a portable persistence format for these objects. Native survival curves are mapped to requested times as right-continuous steps; see surv.coxtime() for the boundary convention.

Value

A list with numeric matrix pred and fitted object fit.

Examples

if (interactive() && requireNamespace("survivalmodels", quietly = TRUE) &&
    requireNamespace("reticulate", quietly = TRUE) &&
    reticulate::py_module_available("pycox")) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:60, ]
  X <- dat[, grep("^x", names(dat))[1:3], drop = FALSE]
  fit <- surv.deepsurv(
    dat$duration, dat$event, X, X[1:4, , drop = FALSE],
    c(50, 100), epochs = 2, seed = 1
  )
  dim(fit$pred)
}

Parametric Survival Prediction Wrapper (Exponential)

Description

Parametric Survival Prediction Wrapper (Exponential)

Usage

surv.exponential(time, event, X, newdata, new.times, obsWeights, id, ...)

Arguments

Value

A list containing the fitted model and predictions.

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:30, ]
x_cols <- grep("^x", names(dat))[1:3]
X <- dat[, x_cols, drop = FALSE]
newX <- X[1:5, , drop = FALSE]
times <- seq(50, 150, by = 50)

fit <- surv.exponential(
  time = dat$duration,
  event = dat$event,
  X = X,
  newdata = newX,
  new.times = times,
  obsWeights = rep(1, nrow(dat)),
  id = NULL
)

dim(fit[["pred"]])

Flexible Parametric Distribution Survival Learner

Description

Fits a weighted parametric survival model using flexsurv::flexsurvreg(). Native survival probabilities are used without risk-score calibration.

Usage

surv.flexsurvreg(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  obsWeights = NULL,
  id = NULL,
  dist = "gengamma",
  ...
)

Arguments

Details

Only single-event, right-censored outcomes are supported. Covariates enter the distribution's location parameter by default; anc can specify covariates on ancillary parameters. Generalized gamma may require suitable initial values, especially in small training folds. Failed optimization is reported as an error rather than silently accepted.

Value

A list with numeric survival matrix pred and fitted object fit.

Examples

if (requireNamespace("flexsurv", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  X <- dat[, "x1", drop = FALSE]
  fit <- surv.flexsurvreg(dat$duration, dat$event, X,
                         X[1:3, , drop = FALSE], c(50, 100), dist = "weibull")
  predict(fit$fit, X[1:3, , drop = FALSE], new.times = c(25, 50, 100))
}

Flexible Parametric Spline Survival Learner

Description

Fits a weighted Royston-Parmar flexible parametric survival model using flexsurv::flexsurvspline().

Usage

surv.flexsurvspline(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  obsWeights = NULL,
  id = NULL,
  k = 1L,
  scale = "hazard",
  ...
)

Arguments

Value

A list with numeric matrix pred and fitted object fit.

Examples

if (requireNamespace("flexsurv", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:40, ]
  X <- dat[, grep("^x", names(dat))[1:3], drop = FALSE]
  fit <- surv.flexsurvspline(
    dat$duration, dat$event, X, X[1:4, , drop = FALSE],
    c(50, 100), k = 1
  )
  dim(fit$pred)
}

Wrapper for Generalized Additive Cox Regression (GAM)

Description

Final Production Wrapper for GAM (Tunable & Robust). Uses gam to fit an additive combination of smooth and linear functions.

Usage

surv.gam(time, event, X, newdata, new.times, obsWeights, id, cts.num = 5, ...)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

if (requireNamespace("mgcv", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:30, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.gam(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times,
    obsWeights = rep(1, nrow(dat)),
    id = NULL,
    cts.num = 5
  )

  dim(fit[["pred"]])
}

Wrapper function for Gradient Boosting (GBM) prediction algorithm

Description

Final Production Wrapper for GBM (Tunable & Robust). Estimates a Cox proportional hazards model via gradient boosting. Uses the Breslow estimator with a step-function approach for the baseline hazard. Includes internal safeguards against C++ crashes and small cross-validation folds.

Usage

surv.gbm(
  time,
  event,
  X,
  newdata,
  new.times,
  obsWeights,
  id,
  n.trees = 1000,
  interaction.depth = 2,
  shrinkage = 0.01,
  cv.folds = 5,
  n.minobsinnode = 10,
  ties = c("breslow", "efron"),
  survival_transform = c("exponential", "product_limit"),
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

if (requireNamespace("gbm", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:30, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.gbm(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times,
    obsWeights = rep(1, nrow(dat)),
    id = NULL,
    n.trees = 20,
    interaction.depth = 1,
    shrinkage = 0.05,
    cv.folds = 0,
    n.minobsinnode = 3
  )

  dim(fit[["pred"]])
}

Wrapper function for Penalized Cox Regression (GLMNET)

Description

Final Production Wrapper for GLMNET (Tunable & Robust). Estimates a penalized Cox model (Lasso, Ridge, or Elastic Net) with automatic lambda selection. Uses the Breslow estimator with a step-function approach for the baseline hazard.

Usage

surv.glmnet(
  time,
  event,
  X,
  newdata,
  new.times,
  obsWeights,
  id,
  alpha = 1,
  nfolds = 10,
  ties = c("breslow", "efron"),
  survival_transform = c("exponential", "product_limit"),
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:30, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.glmnet(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times,
    obsWeights = rep(1, nrow(dat)),
    id = NULL,
    alpha = 1,
    nfolds = 3
  )

  dim(fit[["pred"]])
}

Generalized Random Survival Forest Learner

Description

Fits an honest generalized random survival forest using grf::survival_forest() and returns conditional survival curves.

Usage

surv.grf(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  obsWeights = NULL,
  id = NULL,
  num.trees = 1000L,
  mtry = NULL,
  min.node.size = 15L,
  honesty = TRUE,
  prediction.type = c("Kaplan-Meier", "Nelson-Aalen"),
  seed = 1L,
  ...
)

Arguments

Value

A list with numeric matrix pred and fitted object fit.

Examples

if (requireNamespace("grf", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:40, ]
  X <- dat[, grep("^x", names(dat))[1:3], drop = FALSE]
  fit <- surv.grf(
    dat$duration, dat$event, X, X[1:4, , drop = FALSE],
    c(50, 100), num.trees = 50, seed = 1
  )
  dim(fit$pred)
}

Kaplan-Meier Prediction Algorithm

Description

This prediction algorithm ignores all covariates and computes the marginal Kaplan-Meier survival estimator using the survfit function.

Usage

surv.km(time, event, X, newdata, new.times, obsWeights, id, ...)

Arguments

Value

A list containing:

• fit: A list containing the fitted survfit object.

• pred: A numeric matrix of cross-validated survival predictions evaluated at new.times.

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:30, ]
x_cols <- grep("^x", names(dat))[1:3]
X <- dat[, x_cols, drop = FALSE]
newX <- X[1:5, , drop = FALSE]
times <- seq(50, 150, by = 50)

fit <- surv.km(
  time = dat$duration,
  event = dat$event,
  X = X,
  newdata = newX,
  new.times = times,
  obsWeights = rep(1, nrow(dat)),
  id = NULL
)

dim(fit[["pred"]])

Parametric Survival Prediction Wrapper (Log-Logistic)

Description

Parametric Survival Prediction Wrapper (Log-Logistic)

Usage

surv.loglogistic(time, event, X, newdata, new.times, obsWeights, id, ...)

Arguments

Value

A list containing the fitted model and predictions.

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:30, ]
x_cols <- grep("^x", names(dat))[1:3]
X <- dat[, x_cols, drop = FALSE]
newX <- X[1:5, , drop = FALSE]
times <- seq(50, 150, by = 50)

fit <- surv.loglogistic(
  time = dat$duration,
  event = dat$event,
  X = X,
  newdata = newX,
  new.times = times,
  obsWeights = rep(1, nrow(dat)),
  id = NULL
)

dim(fit[["pred"]])

Parametric Survival Prediction Wrapper (Log-Normal)

Description

Parametric Survival Prediction Wrapper (Log-Normal)

Usage

surv.lognormal(time, event, X, newdata, new.times, obsWeights, id, ...)

Arguments

Value

A list containing the fitted model and predictions.

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:30, ]
x_cols <- grep("^x", names(dat))[1:3]
X <- dat[, x_cols, drop = FALSE]
newX <- X[1:5, , drop = FALSE]
times <- seq(50, 150, by = 50)

fit <- surv.lognormal(
  time = dat$duration,
  event = dat$event,
  X = X,
  newdata = newX,
  new.times = times,
  obsWeights = rep(1, nrow(dat)),
  id = NULL
)

dim(fit[["pred"]])

Component-Wise Cox Boosting Learner

Description

Fits a weighted component-wise Cox proportional-hazards model using mboost::glmboost() and converts its risk score to survival probabilities using SuperSurv's weighted baseline-hazard calibration.

Usage

surv.mboost(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  obsWeights = NULL,
  id = NULL,
  mstop = 100L,
  nu = 0.1,
  center = FALSE,
  ties = c("breslow", "efron"),
  survival_transform = c("exponential", "product_limit"),
  ...
)

Arguments

Value

A list with numeric matrix pred and fitted object fit.

Examples

if (requireNamespace("mboost", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:40, ]
  X <- dat[, grep("^x", names(dat))[1:3], drop = FALSE]
  fit <- surv.mboost(
    dat$duration, dat$event, X, X[1:4, , drop = FALSE],
    c(50, 100), mstop = 20
  )
  dim(fit$pred)
}

Universal Parametric Survival Wrapper

Description

Final Production Wrapper for AFT Models (Weibull, Exponential, LogNormal, LogLogistic). Replaces individual wrappers with one robust, vectorized function.

Usage

surv.parametric(
  time,
  event,
  X,
  newdata,
  new.times,
  obsWeights,
  id,
  dist = "weibull",
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:30, ]
x_cols <- grep("^x", names(dat))[1:3]
X <- dat[, x_cols, drop = FALSE]
newX <- X[1:5, , drop = FALSE]
times <- seq(50, 150, by = 50)

fit <- surv.parametric(
  time = dat$duration,
  event = dat$event,
  X = X,
  newdata = newX,
  new.times = times,
  obsWeights = rep(1, nrow(dat)),
  id = NULL,
  dist = "weibull"
)

dim(fit[["pred"]])

Wrapper function for Ranger Random Survival Forest

Description

Final Production Wrapper for Ranger (Tunable & Fast). Uses the ranger C++ implementation to estimate survival curves.

Usage

surv.ranger(
  time,
  event,
  X,
  newdata,
  new.times,
  obsWeights,
  id,
  num.trees = 500,
  mtry = NULL,
  min.node.size = NULL,
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

if (requireNamespace("ranger", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:30, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.ranger(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times,
    obsWeights = rep(1, nrow(dat)),
    id = NULL,
    num.trees = 10,
    min.node.size = 3
  )

  dim(fit[["pred"]])
}

Wrapper function for Random Survival Forests (RFSRC)

Description

Final Production Wrapper for RFSRC (Tunable & Robust). Estimates a survival random forest using rfsrc.

Usage

surv.rfsrc(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  obsWeights = NULL,
  id = NULL,
  ntree = 1000,
  nodesize = 15,
  mtry = NULL,
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

if (requireNamespace("randomForestSRC", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:30, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.rfsrc(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times,
    ntree = 10,
    nodesize = 3
  )

  dim(fit[["pred"]])
}

Wrapper for Ridge Regression (Penalized Cox)

Description

Final Production Wrapper for Ridge Regression (Tunable & Robust). Estimates a penalized Cox model using a pure Ridge penalty (alpha = 0).

Usage

surv.ridge(
  time,
  event,
  X,
  newdata,
  new.times,
  obsWeights = NULL,
  id = NULL,
  nfolds = 10,
  ties = c("breslow", "efron"),
  survival_transform = c("exponential", "product_limit"),
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

if (requireNamespace("glmnet", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:30, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.ridge(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times,
    nfolds = 3
  )

  dim(fit[["pred"]])
}

Wrapper for Survival Regression Trees (rpart)

Description

Final Production Wrapper for single decision trees. Uses rpart with method="exp" and calculates survival probabilities using the Breslow estimator.

Usage

surv.rpart(
  time,
  event,
  X,
  newdata,
  new.times,
  obsWeights,
  id,
  cp = 0.01,
  minsplit = 20,
  maxdepth = 30,
  ties = c("breslow", "efron"),
  survival_transform = c("exponential", "product_limit"),
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

if (requireNamespace("rpart", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:30, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.rpart(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times,
    obsWeights = rep(1, nrow(dat)),
    id = NULL,
    cp = 0.01,
    minsplit = 5,
    maxdepth = 3
  )

  dim(fit[["pred"]])
}

Penalized Smooth Hazard Survival Learner

Description

Fits an overall hazard model using survPen::survPen() and returns its native survival probabilities. Only single-event, right-censored outcomes and uniform observation weights are supported.

Usage

surv.survPen(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  obsWeights = NULL,
  id = NULL,
  formula = NULL,
  baseline.df = 4L,
  n.legendre = 50L,
  ...
)

Arguments

Details

Nonuniform observation weights are rejected because the backend does not expose case-weighted fitting. The adapter does not implement net survival, relative mortality, or left truncation. Survival curves that increase beyond numerical tolerance cause an error; increase quadrature accuracy rather than silently projecting a materially invalid curve. Custom formulas must remain valid after feature screening; use screen.all when explicitly naming features.

Value

A list with numeric survival matrix pred and fitted object fit.

Examples

if (requireNamespace("survPen", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:80, ]
  X <- dat[, "x1", drop = FALSE]
  fit <- surv.survPen(dat$duration, dat$event, X,
                      X[1:3, , drop = FALSE], c(50, 100), baseline.df = 3)
  dim(fit$pred)
}

Wrapper for Survival Support Vector Machine (survivalsvm)

Description

Final Production Wrapper for SVM (Tunable & Robust). Estimates a survival SVM and calibrates the raw utility scores into survival probabilities using a univariate Cox proportional hazards model.

Usage

surv.svm(
  time,
  event,
  X,
  newdata,
  new.times,
  obsWeights,
  id,
  gamma.mu = 0.1,
  type = "vanbelle2",
  kernel = "lin_kernel",
  opt.meth = "quadprog",
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

if (requireNamespace("survivalsvm", quietly = TRUE) &&
 requireNamespace("quadprog", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:25, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.svm(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times
  )

  dim(fit[["pred"]])
}

Parametric Survival Prediction Wrapper (Weibull)

Description

Parametric Survival Prediction Wrapper (Weibull)

Usage

surv.weibull(time, event, X, newdata, new.times, obsWeights, id, ...)

Arguments

Value

A list containing the fitted model and predictions.

Examples

data("metabric", package = "SuperSurv")
dat <- metabric[1:30, ]
x_cols <- grep("^x", names(dat))[1:3]
X <- dat[, x_cols, drop = FALSE]
newX <- X[1:5, , drop = FALSE]
times <- seq(50, 150, by = 50)

fit <- surv.weibull(
  time = dat$duration,
  event = dat$event,
  X = X,
  newdata = newX,
  new.times = times,
  obsWeights = rep(1, nrow(dat)),
  id = NULL
)

dim(fit[["pred"]])

Wrapper for XGBoost (Robust CV-Tuned + Safe Prediction)

Description

Estimates a Cox proportional hazards model via XGBoost. Incorporates safe Breslow hazard calculation and matrix alignment to prevent C++ crashes.

Usage

surv.xgboost(
  time,
  event,
  X,
  newdata = NULL,
  new.times,
  obsWeights,
  id,
  nrounds = 1000,
  early_stopping_rounds = 10,
  eta = 0.05,
  max_depth = 2,
  min_child_weight = 5,
  lambda = 10,
  subsample = 0.7,
  ties = c("breslow", "efron"),
  survival_transform = c("exponential", "product_limit"),
  ...
)

Arguments

Value

A list containing:

• fit: The fitted model object (e.g., the raw coxph or xgb.Booster object). If the model fails to fit, this may be an object of class try-error.

• pred: A numeric matrix of cross-validated survival predictions evaluated at the specified new.times grid.

Examples

if (interactive() && requireNamespace("xgboost", quietly = TRUE)) {
  data("metabric", package = "SuperSurv")
  dat <- metabric[1:30, ]
  x_cols <- grep("^x", names(dat))[1:3]
  X <- dat[, x_cols, drop = FALSE]
  newX <- X[1:5, , drop = FALSE]
  times <- seq(50, 150, by = 50)

  fit <- surv.xgboost(
    time = dat$duration,
    event = dat$event,
    X = X,
    newdata = newX,
    new.times = times,
    obsWeights = rep(1, nrow(dat)),
    id = NULL,
    nrounds = 5,
    early_stopping_rounds = 2,
    max_depth = 1,
    nthread = 1
  )

  dim(fit[["pred"]])
}

Access SuperSurv training variable names

Description

Returns the covariate names used to fit a SuperSurv object.

Usage

training_variables(object, ...)

## Default S3 method:
training_variables(object, ...)

## S3 method for class 'SuperSurv'
training_variables(object, ...)

Arguments

Value

A character vector of training variable names.