# 11. Extending SuperSurv

This vignette describes the practical contract used by `SuperSurv()` to call survival learners and screening methods. The goal is to make small extensions possible without changing the ensemble algorithm.

## How Learners Are Found

Learners are supplied to `SuperSurv()` by name:

    event.library <- c("surv.coxph", "my.surv.km")

During cross-validation and final fitting, `SuperSurv()` looks up each name as an R function and calls it directly. A custom learner can therefore live in a user script, package, or analysis file, as long as it is available in the R session before calling `SuperSurv()`.

## Learner Wrapper Contract

A survival learner wrapper should have this shape:

    my.surv.learner <- function(time, event, X, newdata, new.times,
                                obsWeights, id, ...) {
      # fit model on X, time, event
      # predict survival probabilities for newdata at new.times
      list(pred = pred_matrix, fit = fitted_object)
    }

The required arguments are:

Argument | Meaning
--- | ---
`time` | numeric observed follow-up time
`event` | event indicator, with `1` for the event and `0` for censoring
`X` | training covariates as a data frame
`newdata` | covariates for prediction as a data frame
`new.times` | time grid where survival probabilities are needed
`obsWeights` | observation weights, possibly `NULL`
`id` | optional cluster or subject identifier, possibly `NULL`
`...` | learner-specific tuning parameters

The returned `pred` must be a numeric matrix with:

- one row per row of `newdata`,
- one column per value of `new.times`,
- entries on the survival-probability scale, usually between `0` and `1`.

If possible, each row should be non-increasing across time. Wrappers commonly clamp small numerical drift back into `[0, 1]`.

The returned `fit` can be any object needed for future prediction. When `control = list(saveFitLibrary = TRUE)`, `SuperSurv()` stores these fitted objects and `predict.SuperSurv()` later calls `predict()` on them.

## Prediction Method Contract

If a custom learner should support prediction on new data after fitting, store a classed object in `fit` and define a matching S3 prediction method:

    predict.my.surv.learner <- function(object, newdata, new.times, ...) {
      pred_matrix
    }

This method should return the same type of matrix as the wrapper’s `pred` component: `nrow(newdata)` rows by `length(new.times)` columns.

## Direct Survival Curves vs Risk Scores

Some survival learners directly return survival curves. In that case, the wrapper usually interpolates the native prediction grid to `new.times`.

Other learners return a risk score or linear predictor. Those wrappers need one extra calibration step:

1. fit the risk-score model,
2. estimate a baseline cumulative hazard on the training data,
3. predict risk scores for `newdata`,
4. convert scores to survival curves with `S(t | x) = exp(-exp(eta(x)) H0(t))`.

Several built-in Cox-style wrappers follow this pattern. The internal helper `safe_breslow_step()` is used by some package wrappers, but it is not exported; custom wrappers should either use a standard package prediction method that already returns survival curves or implement their own baseline-hazard calibration carefully.

## Minimal Custom Learner

The following learner ignores covariates and fits a weighted Kaplan-Meier curve. It is intentionally simple, but it satisfies the full `SuperSurv()` learner contract.

    my.surv.km <- function(time, event, X, newdata, new.times,
                           obsWeights = NULL, id = NULL, ...) {
      if (is.null(obsWeights)) {
        obsWeights <- rep(1, length(time))
      }

      fit_km <- survival::survfit(
        survival::Surv(time, event) ~ 1,
        weights = obsWeights
      )

      step_surv <- stats::stepfun(fit_km$time, c(1, fit_km$surv), right = FALSE)
      surv_probs <- step_surv(new.times)

      pred <- matrix(
        surv_probs,
        nrow = nrow(newdata),
        ncol = length(new.times),
        byrow = TRUE
      )

      fit <- list(object = fit_km)
      class(fit) <- "my.surv.km"

      list(pred = pred, fit = fit)
    }

    predict.my.surv.km <- function(object, newdata, new.times, ...) {
      fit_km <- object$object
      step_surv <- stats::stepfun(fit_km$time, c(1, fit_km$surv), right = FALSE)
      surv_probs <- step_surv(new.times)

      matrix(
        surv_probs,
        nrow = nrow(newdata),
        ncol = length(new.times),
        byrow = TRUE
      )
    }

You can test the wrapper outside the ensemble before adding it to a library:

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

    wrapper_out <- my.surv.km(
      time = dat$duration,
      event = dat$event,
      X = X,
      newdata = X[1:5, , drop = FALSE],
      new.times = times
    )

    dim(wrapper_out[["pred"]])
    #> [1] 5 3
    dim(predict(wrapper_out[["fit"]], newdata = X[1:5, , drop = FALSE], new.times = times))
    #> [1] 5 3

The custom learner can be mixed with built-in learners:

    fit <- SuperSurv(
      time = train$duration,
      event = train$event,
      X = X_train,
      newdata = X_test,
      new.times = seq(50, 300, by = 50),
      event.library = c("surv.coxph", "my.surv.km"),
      cens.library = c("surv.coxph"),
      control = list(saveFitLibrary = TRUE)
    )

    event_weights(fit)

## Screening Method Contract

Screening methods are also supplied by name. A screener should accept the same basic training inputs and return a logical vector with one value per column of `X`:

    my.screen.first3 <- function(time, event, X, obsWeights = NULL, id = NULL, ...) {
      keep <- rep(FALSE, ncol(X))
      keep[seq_len(min(3, ncol(X)))] <- TRUE
      names(keep) <- names(X)
      keep
    }

Use a list entry to pair a learner with one or more screeners:

    fit <- SuperSurv(
      time = train$duration,
      event = train$event,
      X = X_train,
      newdata = X_test,
      new.times = seq(50, 300, by = 50),
      event.library = list(c("surv.coxph", "screen.all", "my.screen.first3")),
      cens.library = c("surv.coxph")
    )

    selected_variables(fit, learner = 2)

## Development Checklist

Before using a custom wrapper in a large ensemble, check:

- `pred` is a numeric matrix with dimensions `nrow(newdata)` by `length(new.times)`,
- predictions are on the survival-probability scale,
- `predict(wrapper_out[["fit"]], newdata, new.times)` returns the same shape when saved fits are needed,
- the wrapper tolerates `obsWeights = NULL` and `id = NULL`,
- all required packages are checked with `requireNamespace()`,
- any screener returns a logical vector aligned with the columns of `X`.

These rules are deliberately small. They allow new learners to be added without changing the SuperSurv ensemble machinery.