Package {survalis}

survalis: Interpretable Survival Machine Learning

Description

survalis provides a unified interface for fitting, predicting, evaluating, tuning, comparing, interpreting and standardising survival machine-learning models across 24 learners.

The seven verbs

The recommended interface, consistent with the funcml package:

fit()

fit a learner by id, returning a survalis_fit.

predict()

typed predictions on a recorded time grid ("survival", "risk", "chf", "hazard", "rmst", "quantile", "median").

evaluate()

resampled performance for a fit or a formula.

tune()

grid search, returning the refit best model.

compare()

paired multi-model leaderboard on shared folds.

interpret()

one entry point to the explanation methods.

estimate()

standardised binary-treatment contrast by G-computation.

Resampling is described by cv(), holdout(), groupcv() and bootstrap(). Discover components with listlearners(), listmetrics() and listmethods(). Custom learners plug into every verb as model = list(fit = , predict = ); see fit().

Author(s)

Maintainer: Imad El Badisy elbadisyimad@gmail.com

See Also

Useful links:

• https://elbadisyimad.com/survalis/

• https://github.com/ielbadisy/survalis

• https://CRAN.R-project.org/package=survalis

• Report bugs at https://github.com/ielbadisy/survalis/issues

Wrap a legacy mlsurv_model as a survalis_fit

Description

Wrap a legacy mlsurv_model as a survalis_fit

Usage

.as_survalis_fit(mlobj, model_id, spec, formula, data, parsed)

Shared split-loop used by evaluate() and compare()

Description

Shared split-loop used by evaluate() and compare()

Usage

.evaluate_splits(
  splits,
  formula,
  data,
  model,
  spec,
  times,
  metrics,
  parsed,
  ncores = 1
)

Standardize learner prediction output to the survmat contract

Description

Internal utility used by ⁠predict_*()⁠ methods and evaluators to coerce raw predictions to a validated survival-probability matrix contract.

Usage

.finalize_survmat(S, times, clamp = TRUE, enforce_monotone = TRUE)

Arguments

Value

A base data.frame with columns named ⁠t=<time>⁠.

0/1 event vector of a fit's training data

Description

0/1 event vector of a fit's training data

Usage

.fit_status_vector(fit)

Infer time points from survmat column names

Description

Internal helper that parses "t=<time>" column names when an explicit time vector is not supplied.

Usage

.infer_survmat_times(S)

Arguments

Value

Numeric vector of inferred times.

Adaptors from interpret() method ids to compute_*() signatures

Description

Adaptors from interpret() method ids to compute_*() signatures

Usage

.interpret_dispatch()

Expand a resampling specification into concrete row-index splits

Description

Expand a resampling specification into concrete row-index splits

Usage

.make_splits(resampling, data, status_col = NULL)

Arguments

Value

A list of ⁠list(analysis = <int>, assessment = <int>, id = <chr>)⁠.

Parse a survival outcome from a model formula

Description

Internal helper that extracts the time and status components from a formula whose left-hand side is Surv(...) or pkg::Surv(...).

Usage

.parse_surv_formula(formula, data)

Arguments

Value

A list with time_col, status_col, event_value, and recode_status.

Reconstruct Cox-style survival curves from linear predictors

Description

Internal helper shared by Cox-family learners to produce comparable survival probabilities from a baseline cumulative hazard and subject-specific linear predictors.

Usage

.predict_cox_from_lp(lp_train, lp_new, y_train, times)

Arguments

Value

A standardized survival-probability data.frame.

Resolve a caller-supplied times argument against the default grid

Description

Resolve a caller-supplied times argument against the default grid

Usage

.resolve_times(times, time, status = NULL, n = 50L)

Arguments

Value

A validated numeric vector (strictly increasing, non-negative; 0 is allowed).

Validate and standardize a survival-probability matrix (survmat)

Description

Internal utility to validate the basic structure of a surv_mat and coerce it to a numeric matrix. Optionally checks column names against times.

Usage

.survmat_as_matrix(S, times = NULL, strict_colnames = FALSE, clamp = FALSE)

Arguments

Value

A numeric matrix.

Tidy data frames from verb result objects

Description

as.data.frame() methods that return the most useful rectangular view of each result object, for downstream plotting or reporting:

Usage

## S3 method for class 'survmat'
as.data.frame(x, ..., format = c("wide", "long"))

## S3 method for class 'survalis_fit'
as.data.frame(x, ...)

## S3 method for class 'survalis_eval'
as.data.frame(x, ...)

## S3 method for class 'survalis_tune'
as.data.frame(x, ...)

## S3 method for class 'survalis_compare'
as.data.frame(x, ...)

## S3 method for class 'survalis_estimate'
as.data.frame(x, ...)

Arguments

Details

• survalis_fit – a one-row model summary (model, engine, formula, n, events).

• survmat (from predict()) – by default the wide prediction matrix with one "t=<time>" column per evaluation time; format = "long" returns one row per observation and time (id, time, value).

• survalis_eval – the per-split metric values (id, metric, value).

• survalis_tune – the scored hyperparameter grid.

• survalis_compare – the model-by-metric leaderboard (model, metric, mean, se).

• survalis_estimate – a one-row summary (estimand, tau, estimate, conf_low, conf_high, model).

Value

A data frame.

Compare several survival learners on shared resampling folds

Description

Evaluates each learner in models on the same set of resampling splits, so the per-fold values are paired across models. Returns a leaderboard plus the full per-split table.

Usage

compare(
  formula,
  data,
  models,
  specs = list(),
  times = NULL,
  resampling = cv(),
  metrics = c("cindex", "ibs"),
  tune = FALSE,
  ncores = 1,
  ...
)

Arguments

Value

A survalis_compare object: leaderboard (model x metric, mean and se), per_split (long), times, resampling, metrics, models, tuned.

Examples

cmp <- compare(Surv(time, status) ~ age + karno + celltype, veteran,
               models = c("coxph", "ranger"), times = c(90, 180, 365),
               resampling = cv(3))
cmp
plot(cmp)

Decision-weighted scores for survival predictions

Description

Scores predicted risks at one or more horizons with a decision-weighted proper score: the loss of the rule "act if predicted risk exceeds c", averaged over thresholds c with a weight w(c). The weight states which risk thresholds matter. Every such score equals a weighted area under the net benefit curve, with weight ⁠(1 - c) w(c)⁠, so a threshold range restricts model comparison to the decisions clinicians actually make.

Usage

dwscore(
  object,
  y,
  times = NULL,
  weight = c("range", "survacc", "brier", "log", "beta"),
  thresholds = c(0.05, 0.2),
  shape = c(2, 18)
)

Arguments

Details

With risk r = 1 - S(t \mid X) and event status D = I(T \le t), the loss is L_w(r, 0) = \int_0^r w(c)\, c\, dc for a subject event free at t and L_w(r, 1) = \int_r^1 w(c) (1 - c)\, dc for a subject with an event by t. Right censoring is handled by inverse probability of censoring weights from the Kaplan-Meier estimate of the censoring distribution: subjects event free at t are weighted by 1 / G(t), subjects with an observed event at U \le t by 1 / G(U-), and subjects censored before t get weight zero. This assumes censoring is independent of the covariates. Range and Beta weights integrate to one, so those losses lie on the scale of an average regret per decision.

In evaluate(), compare() and tune(), use the metric ids "survacc" (SurvAcc, higher is better) and "range:<lower>-<upper>", for example "range:0.05-0.20" (loss, lower is better). Both need a single time.

Value

A data frame with columns time, weight and loss (lower is better for every weight).

Examples

m <- fit(Surv(time, status) ~ age + karno, veteran[1:100, ], "coxph")
S <- predict(m, veteran[-(1:100), ], times = c(90, 180))
y <- Surv(veteran$time[-(1:100)], veteran$status[-(1:100)])
dwscore(S, y)
dwscore(S, y, weight = "brier")
dwscore(S, y, weight = "range", thresholds = c(0.10, 0.30))

# the same scores inside the verbs (single time)
S180 <- predict(m, veteran[-(1:100), ], times = 180)
evaluate(S180, y = y, metrics = c("brier", "survacc", "range:0.05-0.20"))

Standardised causal-style contrast for a binary treatment

Description

Estimates a covariate-adjusted marginal contrast between the two levels of a binary treatment by G-computation (outcome standardisation): a survival model is fitted for Surv(time, status) ~ treatment * (confounders), every subject's outcome is predicted under both treatment levels, and the counterfactual mean survival curves are contrasted.

Usage

estimate(
  formula,
  data,
  model,
  estimand = c("RMST_diff", "RMST_ratio", "survival_diff", "survival_ratio"),
  treatment,
  tau,
  times = NULL,
  spec = list(),
  R = 200,
  conf = 0.95,
  refit = TRUE,
  seed = NULL,
  ...
)

Arguments

Details

Uncertainty is a nonparametric bootstrap over subjects; by default the model is refitted in each replicate (refit = TRUE), which propagates model estimation error. Set refit = FALSE for a faster interval that is conditional on the fitted model.

Value

A survalis_estimate object with estimand, estimate, conf_low, conf_high, conf, treatment, levels, tau, R, refit, boot (replicate estimates) and curves (counterfactual mean survival for each arm on times).

Interpretation

The estimate has a causal reading only under standard identification assumptions: consistency, no unmeasured confounding given the formula covariates, positivity, no interference, and a correctly specified outcome model. For a non-manipulable attribute it is a covariate-adjusted marginal contrast, not a causal effect. This is a plug-in G-formula estimator; it is not doubly robust.

Examples

est <- estimate(Surv(time, status) ~ age + karno + celltype, veteran,
                model = "coxph", estimand = "RMST_diff",
                treatment = "trt", tau = 300, R = 50, seed = 1)
est

Performance of a survival learner

Description

Scores survival predictions in one of three ways:

Resampled

evaluate(fit) or evaluate(formula, data, model) refits the learner on each training split of resampling and scores it on the held-out split (internal validation).

New data

evaluate(fit, newdata = test) scores a fitted learner on data it was not trained on (external or temporal validation).

Supplied predictions

evaluate(S, y = Surv(time, status)) scores an ⁠n x length(times)⁠ matrix of survival probabilities produced elsewhere, for example by another package.

Usage

evaluate(object, ...)

## S3 method for class 'survalis_fit'
evaluate(
  object,
  newdata = NULL,
  times = NULL,
  resampling = cv(),
  metrics = c("cindex", "ibs"),
  ncores = 1,
  ...
)

## S3 method for class 'formula'
evaluate(
  object,
  data,
  model,
  spec = list(),
  times = NULL,
  resampling = cv(),
  metrics = c("cindex", "ibs"),
  ncores = 1,
  ...
)

## S3 method for class 'matrix'
evaluate(object, y, times = NULL, metrics = c("cindex", "ibs"), ...)

Arguments

Value

A survalis_eval object: per_split (long data frame), summary (mean / sd / se / 95% interval per metric), times, resampling (NULL when scored once), metrics, model.

Examples

m <- fit(Surv(time, status) ~ age + karno + celltype, veteran, "ranger",
         spec = list(num.trees = 100))
evaluate(m, times = c(90, 180, 365), resampling = cv(3))

# train / test split
idx <- seq_len(100)
m_tr <- fit(Surv(time, status) ~ age + karno, veteran[idx, ], "coxph")
evaluate(m_tr, newdata = veteran[-idx, ], times = c(90, 180))

# predictions from anywhere
S <- predict(m_tr, veteran[-idx, ], times = c(90, 180))
evaluate(S, y = Surv(veteran$time[-idx], veteran$status[-idx]))

Fit a survival learner

Description

The entry point of the survalis verb interface. fit() selects a learner by id, passes engine arguments through spec, and returns a survalis_fit object that the other verbs (predict(), evaluate(), tune(), interpret(), estimate()) consume.

Usage

fit(formula, data, model, spec = list(), seed = NULL, ...)

Arguments

Value

An object of class c("survalis_fit", "mlsurv_model") with elements model, learner, engine, formula, data, time, status, model_id, and spec.

See Also

predict.survalis_fit(), evaluate(), tune(), compare(), interpret(), estimate(), listlearners()

Examples

m <- fit(Surv(time, status) ~ age + karno + celltype, veteran,
         model = "ranger", spec = list(num.trees = 200))
m

# A custom learner: an exponential AFT model from survival::survreg
expo <- list(
  name = "exponential",
  fit = function(formula, data, ...) survival::survreg(formula, data, dist = "exponential"),
  predict = function(object, newdata, times) {
    rate <- 1 / predict(object, newdata, type = "response")
    exp(-outer(rate, times))
  }
)
m2 <- fit(Surv(time, status) ~ age + karno, veteran, model = expo)
predict(m2, veteran[1:3, ], times = c(90, 180))

Interpret a fitted survival learner

Description

A single entry point to the package's model-agnostic explanation and diagnostic methods. listmethods() lists the method ids with a one-line description of each.

Usage

interpret(fit, method, newdata = NULL, data = NULL, times = NULL, ...)

Arguments

Value

A survalis_interpret object holding the method's result, with method, times, and a plot() method. as.data.frame() returns the result frame. For "survcluster" it is in long format, one row per observation and time: id (row of newdata), cluster, medoid (TRUE for the cluster's medoid curve), time and predicted survival surv. For "roc" and "dca" it is the curve with an eval_time column (and auc for "roc"); for "tree_surrogate" one row per time and feature with the number of splits on it and the tree's r_squared. For "pdp" / "ice" it is one row per curve point (feature, feature_value, id (NA on PDP rows), time, surv, type), for "ale" one row per feature value and time (feature, feature_value, time, ale), and for "calibration" the binned table with its eval_time. For "pdp" and "ale", as.data.frame(x, what = "integrated") returns the curve integrated over time instead (feature, feature_value, integrated).

See Also

For scalar summaries use evaluate(): metrics = "ece" summarises calibration and metrics = "auc" summarises the ROC curve.

Examples

m <- fit(Surv(time, status) ~ age + karno + celltype, veteran, "ranger",
         spec = list(num.trees = 100))
interpret(m, "pdp", feature = "karno", times = c(90, 180))
interpret(m, "varimp", times = c(90, 180))
plot(interpret(m, "roc", eval_time = 180))

Kaplan-Meier curves with a number-at-risk table

Description

Draws Kaplan-Meier curves in a publication style: step curves with censoring marks, the legend inside the panel, an optional log-rank p-value, and a number-at-risk table coloured by group under the plot. Besides the survival function, it draws the risk function, the cumulative hazard, the complementary log-log diagnostic of proportional hazards, and cumulative incidence under competing risks. A fitted survalis model adds its predicted or covariate-adjusted curves, dashed, over the Kaplan-Meier curves.

Usage

kmplot(
  formula,
  data,
  type = c("survival", "risk", "cumhaz", "cloglog"),
  event = NULL,
  model = NULL,
  model.curve = c("predicted", "adjusted"),
  title = NULL,
  xlab = "Time",
  ylab = NULL,
  breaks = NULL,
  pval = TRUE,
  risk.table = TRUE,
  conf.int = FALSE,
  colors = NULL,
  legend.pos = NULL,
  pval.pos = NULL,
  base_size = 10
)

Arguments

Value

A 'patchwork' object (curve over risk table) when the risk table is drawn, otherwise a 'ggplot2' object. Panels combine with patchwork operators, for example kmplot(...) | kmplot(...).

Examples

kmplot(Surv(time, status) ~ trt, data = veteran, risk.table = FALSE)
kmplot(Surv(time, status) ~ trt, data = veteran, type = "cloglog")

# Competing risks: progression versus death without progression
d <- survival::mgus2
d$etime <- ifelse(d$pstat == 1, d$ptime, d$futime)
d$event <- factor(ifelse(d$pstat == 1, 1, 2 * d$death), 0:2,
                  c("censored", "progression", "death"))
kmplot(Surv(etime, event) ~ sex, data = d, risk.table = FALSE)

if (requireNamespace("patchwork", quietly = TRUE)) {
  kmplot(Surv(time, status) ~ trt, data = veteran,
         title = "A. Overall survival", xlab = "Days",
         breaks = seq(0, 1000, 200))

  # Covariate-adjusted curves from a Cox model, over the Kaplan-Meier curves
  m <- fit(Surv(time, status) ~ trt + karno + age, data = veteran,
           model = "coxph")
  kmplot(Surv(time, status) ~ trt, data = veteran, model = m,
         model.curve = "adjusted", breaks = seq(0, 1000, 200))
}

List the survival learners

Description

The ids accepted by the model argument of fit(), evaluate(), compare(), tune() and estimate().

Usage

listlearners(has_tune = FALSE)

Arguments

Value

A data frame with columns learner (the id) and tunable (whether a built-in tuning grid exists). A learner with tunable = FALSE (for example "fastgbm") can still be tuned by passing a grid to tune().

Examples

listlearners()
listlearners(has_tune = TRUE)

List the interpretability methods

Description

The ids accepted by the method argument of interpret().

Usage

listmethods()

Value

A data frame with columns method and summary.

Examples

listmethods()

List the evaluation metrics

Description

The ids accepted by the metrics argument of evaluate() and compare() and the metric argument of tune().

Usage

listmetrics()

Details

Columns:

• metric: short metric name used throughout the package.

• direction: whether higher or lower values are better.

• summary: brief description.

• range: typical value range.

"range:<lower>-<upper>" is a template: write the thresholds into the id, for example "range:0.05-0.20".

Value

A data.frame with one row per metric.

Examples

listmetrics()

Predict from a fitted survival learner

Description

Produces predictions from a fit() object. Every matrix-valued type returns a survmat (an ⁠n x length(times)⁠ numeric matrix carrying its grid in the "times" attribute); the scalar-valued types ("rmst", "quantile", "median") return a numeric vector (or an ⁠n x length(probs)⁠ matrix for a vector probs).

Usage

## S3 method for class 'survalis_fit'
predict(
  object,
  newdata = NULL,
  times = NULL,
  type = c("survival", "risk", "chf", "hazard", "rmst", "quantile", "median"),
  ...
)

Arguments

Value

A survmat for "survival", "risk", "chf", "hazard"; a numeric vector for "rmst", "median" and scalar-probs "quantile"; an ⁠n x length(probs)⁠ matrix for vector probs.

Examples

m <- fit(Surv(time, status) ~ age + karno, veteran, "ranger",
         spec = list(num.trees = 100))
predict(m, veteran[1:5, ], times = c(90, 180, 365))
predict(m, veteran[1:5, ], times = c(90, 180, 365), type = "risk")
predict(m, veteran[1:5, ], type = "rmst", tau = 365)

Re-export Surv from survival

Description

These objects are imported from other packages. Follow the links below to see their documentation.

survival

Surv

Examples

Surv(c(5, 8, 12), c(1, 0, 1))

Resampling specifications for evaluate(), tune() and compare()

Description

These constructors return a lightweight survalis_resampling description that the verb-level functions turn into concrete train/test splits. They do not touch the data themselves, so the same specification can be reused across models to obtain paired comparisons (identical folds via a shared seed).

Usage

cv(v = 5, repeats = 1, strata = "status", seed = NULL)

holdout(prop = 0.75, strata = "status", seed = NULL)

groupcv(group, v = 5, seed = NULL)

bootstrap(times = 25, seed = NULL)

Arguments

Details

• cv() – k-fold cross-validation, optionally repeated, stratified on the event indicator by default.

• holdout() – a single stratified train/test split.

• groupcv() – k-fold cross-validation where whole groups (e.g. centres, subjects with repeated rows) are held out together.

• bootstrap() – resampling with replacement; the out-of-bag rows form the assessment set (Efron-Tibshirani style, suitable for .632 reporting).

Value

An object of class survalis_resampling.

Examples

cv(5)
cv(v = 10, repeats = 3, seed = 1)
holdout(prop = 0.8)
bootstrap(times = 50)

The survmat prediction contract

Description

Internal constructor and validator for survmat, the single prediction container used by the verb-level predict() method. A survmat is an ⁠n x length(times)⁠ numeric matrix carrying its evaluation grid in the "times" attribute (column names "t=<time>" are kept for display and for backward compatibility with the ⁠*_survmat⁠ metric helpers) and the predicted quantity in the "quantity" attribute.

Usage

new_survmat(x, times, quantity = "survival")

validate_survmat(x)

as_survmat(x, times, quantity = "survival")

Arguments

Details

new_survmat() builds the object without checks; validate_survmat() enforces the contract; as_survmat() is the checked constructor used internally after a learner's raw ⁠predict_*()⁠ output has been finalised.

Value

A survmat: a numeric matrix with class c("survmat", "matrix", "array"), attribute "times", and attribute "quantity".

Evaluation grid of a survmat

Description

Returns the numeric time grid of a survmat, reading the "times" attribute and falling back to parsing "t=<time>" column names for objects produced by the legacy ⁠predict_*()⁠ path.

Usage

survmat_times(x)

Arguments

Value

A numeric vector.

Tune a survival learner over a hyperparameter grid

Description

Grid search over resampling folds. Learners listed by listlearners(has_tune = TRUE) have a built-in default grid; any other learner, including a custom one (see fit()), is tuned over the grid you supply, with every configuration scored on the same splits. The best configuration is refit on the full data and returned as a ready-to-use survalis_fit.

Usage

tune(
  formula,
  data,
  model,
  grid = NULL,
  times = NULL,
  resampling = cv(),
  metric = "ibs",
  ncores = 1,
  ...
)

Arguments

Value

A survalis_tune object: fit (the refit survalis_fit at the best configuration), results (the scored grid), best (one-row best config), times, resampling, metric, model.

Examples

tuned <- tune(Surv(time, status) ~ age + karno, veteran, "ranger",
              grid = expand.grid(num.trees = c(100, 300), mtry = 2, min.node.size = c(5, 15)),
              times = c(90, 180), resampling = cv(3), metric = "ibs")
tuned
predict(tuned, veteran[1:3, ], times = c(90, 180))

Veteran's Administration Lung Cancer Trial Data

Description

This is the veteran dataset originally from the survival package, containing data from a randomized trial of lung cancer treatments.

Usage

veteran

Format

A data frame with 137 observations and 8 variables:

trt

Treatment: 1=standard, 2=test

celltype

Cell type: squamous, smallcell, adeno, large

time

Survival time in days

status

Censoring status: 1=dead, 0=alive

karno

Karnofsky performance score (higher = better)

diagtime

Months from diagnosis to randomization

age

Age in years

prior

Prior therapy: 0=no, 10=yes

Source

survival package, originally from Kalbfleisch and Prentice (1980) The Statistical Analysis of Failure Time Data.

Examples

head(veteran)
summary(veteran$time)