Super Learner for conditional survival functions

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

time: Observed follow-up time.
event: Observed event indicator.
X: Training covariate data.frame.
newdata: Test covariate data.frame for prediction (defaults to X).
new.times: Times at which to obtain predicted survivals.
event.library: Character vector of prediction algorithms for the event.
cens.library: Character vector of prediction algorithms for censoring.
id: Cluster identification variable.
verbose: Logical. If TRUE, prints progress messages.
control: List of control parameters for the Super Learner.
cvControl: List of control parameters for cross-validation.
obsWeights: Observation weights.
metalearner: Character string specifying the optimizer (e.g., "brier" or "logloss").
selection: Character. Specifies how the meta-learner combines the base models. Use "ensemble" (default) to calculate a weighted average (convex combination) of the base learners. Use "best" to act as a Discrete Super Learner, which assigns a weight of 1.0 to the single model with the lowest cross-validated risk.
nFolds: Number of cross-validation folds (default: 10).
parallel: Logical. If TRUE, uses future.apply for parallel execution.

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

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.

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. See vignette("extending-supersurv", package = "SuperSurv") for a practical custom learner and screener example.

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)
}
#> surv.coxph_screen.all surv.ridge_screen.all 
#>                     0                     1