Package 'survalis'

Description

Computes a cumulative/dynamic time-dependent AUC using predicted survival probabilities at a specified time point (or the last column if t_star is NULL). Cases are subjects with an observed event by t_star; controls are subjects known to survive beyond t_star. Subjects censored before t_star are handled through IPCW weighting.

Usage

auc_survmat(object, predicted, t_star = NULL)

Arguments

Details

Risk scores are defined as 1 - S(t) at the chosen time. The AUC is computed over case-control pairs using inverse-probability-of-censoring weights for cases and partial credit (0.5) for ties.

Value

A named numeric scalar: "auc".

Examples

y <- survival::Surv(time = veteran$time, event = veteran$status)
sp <- matrix(
  stats::plogis(scale(veteran$karno)),
  ncol = 1,
  dimnames = list(NULL, "t=100")
)
auc_survmat(y, predicted = sp, t_star = 100)

Description

Runs cv_survlearner() for a set of learner names (e.g., "ranger", "coxph") by dynamically dispatching fit_<learner> and predict_<learner> functions. Returns the row‑bound CV results across all requested learners.

Usage

benchmark_default_survlearners(
  formula,
  data,
  learners,
  times,
  metrics = c("cindex", "ibs"),
  folds = 5,
  seed = 123,
  ncores = 1,
  verbose = FALSE,
  suppress_errors = TRUE,
  ...
)

Arguments

Details

Learners are run independently using identical CV splits and scoring settings. Any learner whose fit_*() or predict_*() function is missing will be skipped with a warning. At least one learner must complete successfully or an error is raised.

Value

A data frame of CV results (as returned by cv_survlearner()) with an extra column learner identifying the source learner.

See Also

cv_survlearner(), plot_benchmark(), summarise_benchmark()

Examples

res <- benchmark_default_survlearners(
  Surv(time, status) ~ age + karno + trt,
  data = veteran,
  learners = c("coxph", "rpart"),
  times = c(80, 160),
  metrics = c("cindex", "ibs"),
  folds = 2,
  seed = 1
)
head(res)

Description

Runs nested cross-validation for one or more learners that expose tune_<learner>(), fit_<learner>(), and predict_<learner>(). The outer folds estimate performance, while each inner training split is tuned using the learner's existing tune_*() implementation only on the outer training data.

Usage

benchmark_tuned_survlearners(
  formula,
  data,
  learners,
  times,
  metrics = c("cindex", "ibs"),
  outer_folds = 5,
  inner_folds = 5,
  seed = 123,
  inner_ncores = 1,
  learner_args = list(),
  refit_final = FALSE,
  verbose = FALSE,
  suppress_errors = TRUE,
  ...
)

Arguments

Value

A list of class "nested_surv_benchmark" with components outer_results, outer_summary, selected_params, final_models, and settings.

See Also

benchmark_default_survlearners, cv_survlearner

Examples

res <- benchmark_tuned_survlearners(
  Surv(time, status) ~ age + karno + trt,
  data = veteran,
  learners = c("ranger", "glmnet"),
  times = c(100, 200),
  outer_folds = 3,
  inner_folds = 2
)
res$outer_summary

Description

Extracts the top‑performing learner(s) under a chosen metric from benchmark results, using the average value across folds.

Usage

best_survlearner(benchmark_results, metric, maximize = NULL)

Arguments

Value

A tibble with columns learner, metric, and the selected average value for the best learner(s). Ties are returned as multiple rows.

See Also

benchmark_default_survlearners(), summarise_benchmark()

Examples

res <- tibble::tibble(
  learner = c("coxph", "coxph", "rpart", "rpart"),
  metric = c("cindex", "ibs", "cindex", "ibs"),
  value = c(0.64, 0.19, 0.60, 0.23)
)
best_survlearner(res, metric = "cindex")
best_survlearner(res, metric = "ibs")

Description

Computes the inverse-probability-of-censoring weighted (IPCW) Brier score at a single time t_star.

Usage

brier(object, pre_sp, t_star)

Arguments

Details

The censoring distribution $G(t)$ is estimated via Kaplan-Meier on 1 - status. Observed events before t_star contribute $S(t_i)^2 / G(t_i)$; those at risk at t_star contribute $(1 - S(t^{*}))^2 / G(t^{*})$. Returns NA if $G(t^{*})$ is undefined or zero.

Value

A named numeric scalar: "brier".

Examples

y <- survival::Surv(time = veteran$time, event = veteran$status)
pre_sp <- stats::plogis(scale(veteran$karno))
brier(y, pre_sp = pre_sp, t_star = 100)

Description

Computes Harrell's concordance index using predicted survival probabilities at a specified time point (or the last column if t_star is NULL).

Usage

cindex_survmat(object, predicted, t_star = NULL)

Arguments

Details

Risk scores are defined as 1 - S(t) at the chosen time. Ties receive partial credit (0.5). Pairs not comparable due to censoring are excluded.

Value

A named numeric scalar: "C index".

Examples

y <- survival::Surv(time = veteran$time, event = veteran$status)
sp <- matrix(
  stats::plogis(scale(veteran$karno)),
  ncol = 1,
  dimnames = list(NULL, "t=100")
)
cindex_survmat(y, predicted = sp, t_star = 100)

Description

Computes ALE curves for a numeric (continuous) feature with respect to survival probabilities at one or more evaluation times. ALE summarizes the average local effect of changing a feature within small intervals, is robust to correlated features, and is centered to have mean zero.

Usage

compute_ale(model, newdata, feature, times, grid.size = 20)

Arguments

Details

For consecutive quantile bins $[z_k, z_{k+1}]$ of the target feature, ALE integrates the local change in the model prediction when moving the feature from $z_k$ to $z_{k+1}$ while holding all other features at their observed values, and then accumulates these differences across bins. For survival models, predictions are survival probabilities at times. The returned ALE curves are centered (mean zero across the grid) per time.

Value

A list with:

ale

A data frame with columns feature_value and one column per time ("t=<time>") containing centered ALE effects.

integrated

If multiple times were provided, a data frame with columns feature_value and integrated_ale equal to the mean of per-time ALE effects across times; otherwise NULL.

See Also

plot_ale(), compute_pdp()

Examples

mod <- fit_coxph(Surv(time, status) ~ age + karno + celltype, data = veteran)
ale_res <- compute_ale(
  model = mod,
  newdata = veteran,
  feature = "karno",
  times = c(80, 160),
  grid.size = 8
)
head(ale_res$ale)

Description

Computes a nonparametric calibration curve for a survival model at one evaluation time by binning predicted survival probabilities and comparing bin-wise means to Kaplan-Meier-based observed survival, with bootstrap CIs.

Usage

compute_calibration(
  model,
  data,
  time,
  status,
  eval_time,
  n_bins = 10,
  n_boot = 100,
  seed = 123,
  learner_name = NULL
)

Arguments

Details

Predicted survival at eval_time is obtained from the appropriate ⁠predict_<learner>()⁠. Predictions are split into n_bins quantile bins. For each bin, the function reports: mean predicted survival, observed survival at eval_time from a Kaplan-Meier fit on the bin's rows, and bootstrap percentile (2.5%, 97.5%) CIs on the observed survival computed by resampling rows with replacement.

Value

A list with components:

calibration_table

A data frame with columns bin, mean_pred_surv, observed_surv, lower_ci, upper_ci.

eval_time

The evaluation time used.

n_bins

Number of bins.

n_boot

Number of bootstrap resamples.

learner

The learner label (from learner_name or model$learner).

See Also

plot_calibration()

Examples

mod <- fit_coxph(Surv(time, status) ~ age + karno + celltype, data = veteran)
calib <- compute_calibration(
  model = mod,
  data = veteran,
  time = "time",
  status = "status",
  eval_time = 80,
  n_bins = 4,
  n_boot = 5,
  seed = 1
)
head(calib$calibration_table)

Description

For a single individual (one-row newdata), propose feature changes that maximize survival probability at a target time, subject to optional per-feature change costs and bounds inferred from the training data in model$data.

Usage

compute_counterfactual(
  model,
  newdata,
  times,
  target_time,
  features_to_change = NULL,
  grid.size = 100,
  max.change = NULL,
  cost_penalty = 0.01
)

Arguments

Details

For each candidate feature, the function sweeps over plausible values (numeric grid between observed min/max; all other levels for categorical), predicts survival at target_time, and reports the best penalized gain relative to the original value. Survival predictions are obtained via a corresponding predict_* function inferred from model$learner (e.g., predict_coxph for learner = "coxph").

Value

A data.frame with one row per feature considered and columns: feature, original_value, suggested_value, survival_gain, change_cost, penalized_gain.

Examples

df <- veteran
df$A <- df$trt
mod <- fit_coxph(survival::Surv(time, status) ~ A + age + karno, data = df)

cf <- compute_counterfactual(
  model = mod,
  newdata = df[1, , drop = FALSE],
  times = c(50, 100, 150),
  target_time = 100,
  features_to_change = c("A", "age", "karno"),
  grid.size = 10,
  cost_penalty = 0.02
)
head(cf)

Description

Estimates global and time-varying interaction strengths of model predictions, using a Friedman-H style decomposition adapted to survival partial dependence. Works with any mlsurv_model that has a matching ⁠predict_*()⁠ method returning survival probabilities.

Usage

compute_interactions(
  model,
  data,
  times,
  target_time = NULL,
  features = NULL,
  type = c("1way", "heatmap", "time"),
  grid.size = 30,
  batch.size = 100
)

Arguments

Details

For a target time $t^{*}$, let $f(x)$ be the predicted survival probability. For feature $j$, we approximate a decomposition:

$f(x) \approx f_j(x_j) + f_{-j}(x_{-j})$

by Monte Carlo marginalization over subsets of features using random sampling from the empirical distribution in data. The reported interaction strength is:

$H_j(t^{*}) = \sqrt{ \frac{\sum ( f(x) - \{ \tilde f_j(x_j) + \tilde f_{-j}(x_{-j}) \})^2 }{ \sum f(x)^2 } } ,$

clipped to [0, 1]. Pairwise heatmaps are computed analogously for $(j, k)$.

Larger values indicate stronger non-additivity (interaction) involving the feature(s). The "time" mode repeats the computation across all times to show dynamics.

Value

A data frame whose structure depends on type:

• "1way": columns feature, interaction.

• "heatmap": columns feature1, feature2, interaction (symmetric with zeros on the diagonal).

• "time": columns feature, time, interaction.

References

Friedman, J. H., and Popescu, B. E. (2008). Predictive learning via rule ensembles. Annals of Applied Statistics. (Friedman's $H$ interaction measure.)

Examples

mod <- fit_coxph(Surv(time, status) ~ age + karno + trt, data = veteran)
times <- c(80, 160)
compute_interactions(
  model = mod,
  data = veteran,
  times = times,
  target_time = 80,
  features = c("age", "karno"),
  type = "1way",
  grid.size = 6
)

Description

Computes partial dependence (PDP) and/or individual conditional expectation (ICE) curves of predicted survival probabilities for a single feature at one or more evaluation times. Works with any learner fitted via ⁠fit_*()⁠ that exposes a matching ⁠predict_*()⁠ method returning survival probabilities.

Usage

compute_pdp(model, data, feature, times, method = "pdp+ice", grid.size = 20)

Arguments

Details

For numeric features, a regular grid over the observed range is used; for categorical features, all observed levels are used. For each grid value, predictions are made for every row of data with the feature forced to the grid value, yielding ICE curves per row and PDP as the average across rows.

If multiple times are supplied, outputs are stacked in long format with a time column; an additional integrated PDP is computed via trapezoidal rule when more than one time is provided.

Value

A list with elements:

results

Long data frame with columns: surv_prob, time, type (pdp/ice), .id (row id for ICE), and the analyzed feature.

pdp_integrated

(Optional) Data frame with feature and integrated_surv (time-integrated PDP), present only if length(times) > 1 and PDP was requested.

Examples

mod <- fit_coxph(Surv(time, status) ~ age + karno + trt, data = veteran)
pdp_age <- compute_pdp(
  model = mod,
  data = veteran,
  feature = "age",
  times = c(80, 160),
  method = "pdp+ice",
  grid.size = 8
)
head(pdp_age$results)

Description

Estimates per-feature contributions (à la SHAP) to the predicted survival probability for a single observation at one or more time points. For each time, the method samples random feature orders, marginalizes future features with values from a baseline dataset, and accumulates the marginal effects of adding each feature back.

Usage

compute_shap(
  model,
  newdata,
  baseline_data,
  times,
  sample.size = 100,
  aggregate = FALSE,
  method = c("meanabs", "integral")
)

Arguments

Details

The prediction function is inferred from model$learner as predict_<learner> and called with signature predict_fun(model, newdata, times = times). Factor levels in newdata are harmonized to those in model$data.

Value

If aggregate = FALSE: a data frame with columns feature, phi, and time (one row per feature per time). If aggregate = TRUE: a data frame with columns feature and phi (one row per feature), with attribute "shap_method" set to the aggregation used.

See Also

plot_shap(), the various predict_* methods (e.g. predict_coxph())

Examples

mod <- fit_coxph(survival::Surv(time, status) ~ age + karno + celltype, data = veteran)

shap_td <- compute_shap(
  model         = mod,
  newdata       = veteran[100, , drop = FALSE],
  baseline_data = veteran,
  times         = c(100, 200),
  sample.size   = 5,
  aggregate     = FALSE
)
head(shap_td)

shap_meanabs <- compute_shap(
  model         = mod,
  newdata       = veteran[100, , drop = FALSE],
  baseline_data = veteran,
  times         = c(100, 200),
  sample.size   = 5,
  aggregate     = TRUE,
  method        = "meanabs"
)
head(shap_meanabs)

Description

Builds a sparse, locally weighted linear surrogate model to explain a fitted survival model's prediction at a specific target time for a single instance. Categorical features are binarized relative to the instance of interest; local weights are computed from feature-space proximity (Gower by default); and a penalized (lasso) or unpenalized linear model is fit to approximate the model's predicted survival probability at target_time.

Usage

compute_surrogate(
  model,
  newdata,
  baseline_data,
  times,
  target_time,
  k = 5,
  dist.fun = "gower",
  gower.power = 5,
  kernel.width = NULL,
  penalized = TRUE,
  exclude = NULL
)

Arguments

Details

Target: The surrogate approximates $S(t^{*} \mid x)$ returned by the underlying model at target_time. The nearest column in times is used.

Weights: Locality weights are computed from distances between baseline_data rows and newdata. With "gower", weights are $(1 - \mathrm{gower\_dist})^{\mathrm{gower.power}}$; otherwise Gaussian $\exp\{-d^2 / \mathrm{kernel.width}^2\}^{1/2}$.

Sparsity: When penalized=TRUE, a glmnet path is fit and the solution with degrees of freedom closest to k is selected (preferring exactly k if available).

Value

A data frame with one row per selected feature containing:

feature

Feature name (after recoding).

feature_value

Value of the feature in newdata.

effect

Local contribution $\beta_j \cdot x_j$ at target_time.

target_time

The explanation time (copied for plotting).

Rows are ordered by decreasing $|effect|$.

Examples

mod <- fit_coxph(Surv(time, status) ~ age + karno + celltype, data = veteran)
local_expl <- compute_surrogate(
  model = mod,
  newdata = veteran[2, , drop = FALSE],
  baseline_data = veteran,
  times = c(80, 160),
  target_time = 80,
  k = 3
)
head(local_expl)

Description

Fits decision tree surrogate models to approximate the predictions of a fitted survival model at one or more evaluation times. This allows users to gain interpretable, rule-based approximations of complex survival models.

Usage

compute_tree_surrogate(model, data, times, minsplit = 10, cp = 0.01)

Arguments

Details

For each evaluation time, the function:

1. Predicts survival probabilities from the fitted model.

2. Excludes survival outcome columns (time, status, event) from the predictors.

3. Fits a decision tree to approximate the predicted probabilities.

4. Computes the R between the model predictions and the surrogate predictions.

5. Counts the number of splits per feature.

If multiple times are provided, results are stored for each time point.

Value

An object of class "tree_surrogate", containing:

• times: the evaluation times.

• results: a list with one element per time, each containing:

  • tree: the fitted rpart object.

  • r_squared: the R of the surrogate model vs. the original predictions.

  • split_count: a table of feature split counts.

• dynamic: logical indicating if more than one time was used.

Examples

mod_ranger <- fit_ranger(Surv(time, status) ~ age + karno + celltype, data = veteran)
tree_ranger <- compute_tree_surrogate(
  model = mod_ranger,
  data = veteran,
  times = c(100, 200, 300)
)

Description

Estimates feature importance by measuring the change in a survival metric after permuting each feature.

Usage

compute_varimp(
  model,
  times,
  metric = "ibs",
  n_repetitions = 10,
  seed = NULL,
  subset = NULL,
  importance_type = c("delta", "mean")
)

Arguments

Details

For each feature, rows are permuted n_repetitions times, predictions are recomputed, and the chosen metric is compared to the baseline (unpermuted) value. The scaled_importance rescales values to sum to 100%.

Value

A data.frame with columns:

• feature: feature name,

• value: importance value (change in metric),

• scaled_importance: percent-scaled importance (see Details).

Examples

mod <- fit_coxph(survival::Surv(time, status) ~ age + karno + celltype, data = veteran)
imp <- compute_varimp(
  model = mod,
  times = 80,
  metric = "brier",
  n_repetitions = 3,
  seed = 1,
  subset = 40
)
head(imp)

Description

Visualizes per-fold metric values from cv_survlearner using a boxplot with jittered points.

Usage

cv_plot(cv_results)

Arguments

Value

A ggplot2 object.

Examples

cv_results <- tibble::tibble(
  metric = c("cindex", "cindex", "ibs", "ibs"),
  value = c(0.62, 0.66, 0.19, 0.21)
)
cv_plot(cv_results)

Description

Produces mean, standard deviation, standard error, and 95\ for each metric returned by cv_survlearner.

Usage

cv_summary(cv_results)

Arguments

Value

A tibble with columns: metric, mean, sd, n, se, lower, upper.

Examples

cv_results <- tibble::tibble(
  metric = c("cindex", "cindex", "ibs", "ibs"),
  value = c(0.62, 0.66, 0.19, 0.21)
)
cv_summary(cv_results)

Description

Runs k-fold cross-validation for any pair of fit_fun/pred_fun that follow the package's learner contracts, and returns tidy per-fold metric values. Fold iteration is handled by functionals::fmapn() with optional parallel execution and a progress bar.

Usage

cv_survlearner(
  formula,
  data,
  fit_fun,
  pred_fun,
  times,
  metrics = c("cindex", "ibs"),
  folds = 5,
  seed = 123,
  verbose = FALSE,
  ncores = 1,
  pb = interactive(),
  ...
)

Arguments

Details

The routine:

1. Validates Surv(...) on the LHS and warns against using . in formulas.

2. Drops rows with missing values in any variables referenced by formula.

3. Supports Surv(time, status == k) by recoding the status to 0/1.

4. Builds stratified v-folds on the status indicator (rsample).

5. For each fold: fits on the analysis set, predicts on the assessment set, and computes metrics.

Fold iteration is performed via functionals::fmapn(), which preserves per-fold identifiers (id, fold) and returns a list ready for dplyr::bind_rows().

Value

A tibble with columns: splits (rsample split object), id, fold, metric, and value.

See Also

fmapn

Examples

cv_results <- cv_survlearner(
  formula = Surv(time, status) ~ age + karno,
  data = veteran,
  fit_fun = fit_coxph,
  pred_fun = predict_coxph,
  times = c(80, 160),
  metrics = c("cindex", "ibs"),
  folds = 2,
  seed = 1
)

Description

Performs v‑fold cross‑validation for the NNLS stacking meta‑learner over a fixed set of base learners and their predictions. On each fold, stacking weights are learned on the analysis set and evaluated on the assessment set.

Usage

cv_survmetalearner(
  formula,
  data,
  times,
  base_models,
  base_preds,
  folds = 5,
  metrics = c("cindex", "ibs"),
  seed = 123,
  verbose = TRUE
)

Arguments

Details

For each fold: (1) subset base_preds to the analysis indices; (2) learn time‑specific NNLS weights with fit_survmetalearner;

(3) predict stacked survival on the assessment set with predict_survmetalearner; (4) compute requested metrics. After CV, a final meta‑learner is fit on the full data.

Value

An object of class "cv_survmetalearner_result" with components:

model

Final "survmetalearner" fit on all data.

cv_results

Per‑fold metric values (tibble).

summary

Fold‑aggregated mean and sd by metric (tibble).

folds, metrics

CV settings.

See Also

fit_survmetalearner, predict_survmetalearner, plot_survmetalearner_weights

Examples

form <- Surv(time, status) ~ age + karno + trt
times <- c(80, 160)
mod_cox <- fit_coxph(form, data = veteran)
mod_rpart <- fit_rpart(form, data = veteran)
base_models <- list(coxph = mod_cox, rpart = mod_rpart)
base_preds  <- list(
  coxph = predict_coxph(mod_cox, veteran, times),
  rpart = predict_rpart(mod_rpart, veteran, times)
)

cv_res <- cv_survmetalearner(
  formula = form, data = veteran, times = times,
  base_models = base_models, base_preds = base_preds,
  folds = 2, metrics = c("cindex", "ibs"), seed = 1, verbose = FALSE
)

cv_res$summary
plot_survmetalearner_weights(cv_res$model)

Description

Computes a binned Expected Calibration Error at time t_star, using quantile-based bins of predicted survival probabilities.

Usage

ece_survmat(object, sp_matrix, t_star, n_bins = 10L, p = 1, weighted = TRUE)

Arguments

Details

Let $\hat{S}_k(t^*)$ be the mean predicted survival in bin $k$ and $\tilde{S}_k(t^*)$ the Kaplan-Meier survival at $t^*$ in that bin. The (weighted) ECE is

$\mathrm{ECE}(t^*) = \left( \sum_k w_k \, |\hat{S}_k(t^*) - \tilde{S}_k(t^*)|^p \right)^{1/p}$

with $w_k = n_k / N$.

Value

A named numeric scalar: "ece".

Examples

y <- survival::Surv(
  time = c(1, 2, 3, 4, 6, 7, 8, 9),
  event = c(1, 1, 0, 1, 0, 1, 1, 0)
)
sp <- cbind("t=5" = c(0.15, 0.20, 0.35, 0.40, 0.55, 0.65, 0.75, 0.80))
ece_survmat(y, sp_matrix = sp, t_star = 5, n_bins = 4)

Description

Fits an additive hazards regression model using timereg's aalen and returns an mlsurv_model compatible with the survalis workflow.

Usage

fit_aalen(formula, data, max.time = NULL, n.sim = 0, resample.iid = 1)

Arguments

Details

The Aalen model assumes an additive hazard:

$\lambda(t \mid X) = \beta_0(t) + X^\top \beta(t),$

with nonparametric cumulative coefficient functions.

Value

A list of class "mlsurv_model" with elements: model, learner="aalen", engine="timereg", formula, data, time, status.

Examples

mod_aalen <- fit_aalen(
    Surv(time, status) ~ trt + karno + age,
    data = veteran
  )
  head(predict_aalen(mod_aalen, newdata = veteran[1:5, ], times = c(50, 100, 150)))

Description

Fits an accelerated failure time (AFT) model via aftgee, which implements GEE methodology for censored survival data. Returns an mlsurv_model-compatible object used throughout the package.

Usage

fit_aftgee(formula, data, corstr = "independence")

Arguments

Details

The AFT model assumes $\log(T) = X \beta + \epsilon$, where $T$ is survival time, $X$ is the covariate matrix, and $\epsilon$ is an error term whose distribution determines the baseline survival. aftgee estimates $\beta$ using GEE. In this wrapper we set id = NULL, assuming one observation per subject.

Value

An object of class mlsurv_model with components:

• model: the fitted aftgee model.

• learner: "aftgee".

• formula: the survival formula.

• data: the training data.

References

Jin, Z., Lin, D. Y., Wei, L. J., & Ying, Z. (2003). Rank-based inference for the accelerated failure time model. Biometrika, 90(2), 341-353.

Examples

mod <- fit_aftgee(
  Surv(time, status) ~ trt + karno + age,
  data = veteran
)
head(predict_aftgee(mod, newdata = veteran[1:5, ], times = c(20, 60, 120)))

Description

Fits a right‐censored survival model using BART's surv.bart and returns an mlsurv_model compatible with the survalis pipeline.

Usage

fit_bart(formula, data, K = 3, ...)

Arguments

Details

The response must be of class Surv(..., type = "right"). The fitted object stores the engine's internal evaluation times in $eval_times (from bart_fit$times) for downstream prediction alignment.

Value

An object of class mlsurv_model with elements:

model

Fitted BART::surv.bart object.

learner

"bart".

formula, data

Original inputs.

eval_times

Engine's internal time grid used for prediction.

See Also

predict_bart, surv.bart

Examples

ex_data <- veteran[1:40, c("time", "status", "age", "karno", "celltype")]
mod_bart <- fit_bart(
  Surv(time, status) ~ age + karno + celltype,
  data = ex_data,
  K = 1,
  ntree = 5,
  ndpost = 20,
  nskip = 5,
  mc.cores = 1,
  seed = 42
)

Description

Fits a survival boosting model using mboost's blackboost with a Cox proportional hazards loss (mboost::CoxPH()) and shallow tree base-learners (partykit). Returns an mlsurv_model compatible with the survalis pipeline.

Usage

fit_blackboost(
  formula,
  data,
  weights = NULL,
  mstop = 100,
  nu = 0.1,
  minsplit = 10,
  minbucket = 4,
  maxdepth = 2,
  ...
)

Arguments

Details

The base-learner is a conditional inference tree controlled by partykit::ctree_control(). The loss is the partial likelihood for Cox PH via mboost::CoxPH(). Use mstop and nu to control complexity.

Value

An object of class mlsurv_model with elements:

model

Fitted mboost model.

learner

"blackboost".

formula, data, time, status

Original inputs/metadata.

References

Bühlmann P, Hothorn T (2007). Boosting algorithms: regularization, prediction and model fitting. Statistical Science.

Examples

mod <- fit_blackboost(
    Surv(time, status) ~ age + karno + celltype,
    data = veteran
  )
  head(predict_blackboost(mod, newdata = veteran[1:5, ], times = c(100, 200)))

Description

Fits an ensemble of k–nearest neighbour survival learners via bnnSurvival. The fitted object is standardized to the mlsurv_model contract used in survalis.

Usage

fit_bnnsurv(
  formula,
  data,
  k = 5,
  num_base_learners = 10,
  num_features_per_base_learner = NULL,
  metric = "mahalanobis",
  weighting_function = function(x) x * 0 + 1,
  replace = TRUE,
  sample_fraction = NULL
)

Arguments

Details

The native engine returns full survival curves on an internal time grid. See predict_bnnsurv for how these are post–processed and (optionally) interpolated to user–requested times.

Value

An object of class "mlsurv_model" with elements:

model

The underlying bnnSurvival fit.

learner

Scalar "bnnsurv".

engine

Scalar "bnnSurvival".

formula, data

Inputs preserved for downstream use.

time, status

Character names of the survival outcome fields.

Engine

Uses bnnSurvival::bnnSurvival. This wrapper calls the engine via requireNamespace("bnnSurvival", quietly = TRUE) and stores the native model in $model.

See Also

predict_bnnsurv(), tune_bnnsurv()

Examples

mod <- fit_bnnsurv(
  Surv(time, status) ~ age + karno + diagtime + prior,
  data = veteran
)
head(predict_bnnsurv(mod, newdata = veteran[1:5, ], times = c(50, 100)))

Description

Fits a survival forest model using the party::cforest() implementation of conditional inference trees for right-censored survival data.

Usage

fit_cforest(
  formula,
  data,
  teststat = "quad",
  testtype = "Univariate",
  mincriterion = 0,
  ntree = 500,
  mtry = 5,
  replace = TRUE,
  fraction = 0.632,
  ...
)

Arguments

Details

This function wraps party::cforest() to fit a conditional inference forest for survival analysis, returning an mlsurv_model object compatible with predict_cforest() and the survalis framework.

Value

An object of class "mlsurv_model", containing:

Examples

mod <- fit_cforest(Surv(time, status) ~ age + celltype + karno, data = veteran)
head(predict_cforest(mod, newdata = veteran[1:5, ], times = c(100, 200)))

Description

Fits a Cox proportional hazards regression model using the survival::coxph() function, and returns an object compatible with the mlsurv_model interface.

Usage

fit_coxph(formula, data, ...)

Arguments

Details

The fitted object is stored along with metadata such as the learner name ("coxph"), original formula, data, and names of the time and status variables. The function requires the survival and pec packages.

Value

An object of class "mlsurv_model" containing:

• model – the fitted coxph object

• learner – the string "coxph"

• formula – the survival formula used

• data – the training dataset

• time, status – names of the survival outcome variables

Examples

mod_cox <- fit_coxph(Surv(time, status) ~ age + karno + celltype, data = veteran)
summary(mod_cox)

Description

This function fits a fully parametric survival regression model using the flexsurv package. It supports a variety of parametric distributions (e.g., Weibull, exponential, log-normal) and returns a model object compatible with the mlsurv_model interface for downstream survival predictions.

Usage

fit_flexsurvreg(formula, data, dist = "weibull", ...)

Arguments

Value

An object of class mlsurv_model containing:

• model - the fitted flexsurvreg model

• learner - string identifier "flexsurvreg"

• formula - the model formula

• data - the training data

• time - the name of the time-to-event column

• status - the name of the event indicator column

Examples

mod_flex <- fit_flexsurvreg(Surv(time, status) ~ age + celltype + karno,
                            data = veteran,
                            dist = "weibull")

Description

Fits a Cox proportional hazards model with elastic net regularization using glmnet. The function wraps cv.glmnet to select the optimal penalty parameter $\lambda$ by cross-validation.

Usage

fit_glmnet(formula, data, alpha = 1, ...)

Arguments

Value

An object of class "mlsurv_model" containing:

• model – the fitted cv.glmnet object

• learner – the string "glmnet"

• formula, data, time, and status metadata

See Also

cv.glmnet, predict_glmnet

Examples

mod_glmnet <- fit_glmnet(
  Surv(time, status) ~ age + karno + celltype,
  data = veteran
)

summary(mod_glmnet$model)

Description

Fits an Oblique Random Survival Forest using the aorsf package. This method builds an ensemble of oblique decision trees for survival analysis, where splits are based on linear combinations of features, allowing for improved performance in high-dimensional or correlated feature settings.

Usage

fit_orsf(formula, data, ...)

Arguments

Details

ORSF models extend traditional Random Survival Forests by allowing oblique splits, which can improve prediction accuracy when predictors are correlated. Missing data are omitted by default (na_action = "omit").

Value

An object of class "mlsurv_model" containing:

• model: The fitted aorsf ORSF model object.

• learner: Character string, always "orsf".

• formula: The survival formula used.

• data: The training dataset.

• time: Name of the survival time variable.

• status: Name of the event indicator variable.

References

Jaeger BC, Long DL, Long DM, Sims M, Szychowski JM, Min YI, Bandyopadhyay D. Oblique random survival forests. Annals of Applied Statistics. 2019;13(3):1847-1883. doi:10.1214/19-AOAS1261

Examples

mod <- fit_orsf(Surv(time, status) ~ age + karno, data = veteran)
summary(mod)

Description

This function fits a survival random forest model using the ranger package and returns an object compatible with the mlsurv_model class.

Usage

fit_ranger(formula, data, ...)

Arguments

Details

This function wraps ranger for survival analysis and stores the result in a standardized mlsurv_model object.

Value

An object of class "mlsurv_model" containing:

• model - the fitted ranger model

• learner - character string "ranger"

• formula - the model formula

• data - training data used to fit the model

See Also

predict_ranger, tune_ranger, ranger

Examples

mod <- fit_ranger(
  Surv(time, status) ~ age + karno + celltype,
  data = veteran,
  num.trees = 25
)
summary(mod)

Description

Fits a survival tree using the rpart package with an exponential splitting rule. This learner is compatible with the mlsurv_model interface and can be used with the cv_survlearner() and ⁠tune_*()⁠ functions in the survalis framework.

Usage

fit_rpart(
  formula,
  data,
  minsplit = 20,
  minbucket = round(minsplit/3),
  cp = 0.01,
  maxcompete = 4,
  maxsurrogate = 5,
  usesurrogate = 2,
  xval = 10,
  surrogatestyle = 0,
  maxdepth = 30
)

Arguments

Details

This function fixes the method = "exp" argument to fit an exponential splitting survival tree, which models the hazard function assuming exponential survival within terminal nodes.

Value

An object of class "mlsurv_model" containing:

• model – fitted rpart survival tree object

• learner – "rpart"

• formula, data, time, and status

References

Therneau TM, Atkinson EJ. (2019). An Introduction to Recursive Partitioning Using the RPART Routines. Mayo Clinic.

Examples

mod_rpart <- fit_rpart(Surv(time, status) ~ age + karno + celltype, data = veteran)
pred_rpart <- predict_rpart(mod_rpart, newdata = veteran[1:5, ], times = c(100, 200, 300))
head(pred_rpart)

Description

Fits a Random Survival Forest for right-censored time-to-event data using randomForestSRC and returns a standardized mlsurv_model compatible with the survalis framework.

Usage

fit_rsf(formula, data, ntree = 500, mtry = NULL, nodesize = 15, ...)

Arguments

Details

RSF extends random forests to survival data by growing an ensemble of survival trees on bootstrap samples and aggregating survival functions across trees.

Value

An object of class mlsurv_model, a named list with elements:

model

The fitted randomForestSRC::rfsrc object.

learner

Character scalar identifying the learner ("rsf").

engine

Character scalar naming the engine ("randomForestSRC").

formula

The original survival formula.

data

The training dataset (or a minimal subset needed for prediction).

time

Name of the survival time variable.

status

Name of the event indicator (1 = event, 0 = censored).

References

Ishwaran H, Kogalur UB, Blackstone EH, Lauer MS (2008). Random survival forests. Annals of Applied Statistics, 2(3):841-860.

Examples

mod_rsf <- fit_rsf(Surv(time, status) ~ age + celltype + karno,
                   data = veteran, ntree = 200)

times <- c(100, 200, 300)
pred_probs <- predict_rsf(mod_rsf, newdata = veteran[1:5, ], times = times)
print(round(pred_probs, 3))

Description

Fits a Cox proportional hazards model with automated predictor selection using pec's selectCox(), returning an mlsurv_model object compatible with the survalis evaluation and cross‑validation pipeline.

Usage

fit_selectcox(formula, data, rule = "aic")

Arguments

Details

This wrapper standardizes the return object to the mlsurv_model contract so downstream prediction and evaluation behave consistently across learners.

Value

An object of class mlsurv_model, a named list with elements:

model

The fitted pec::selectCox model.

learner

Character scalar identifying the learner ("selectcox").

engine

Character scalar naming the engine ("selectCox").

formula

The original survival formula.

data

The training dataset (or a minimal subset needed for prediction).

rule

The selection rule used.

Engine

Uses pec::selectCox. Selection can be driven by Akaike's Information Criterion (rule = "aic") or by p‑value thresholds (rule = "p"), as implemented by pec.

References

Mogensen UB, Ishwaran H, Gerds TA (2012). Evaluating Random Forests for Survival Analysis using pec. Gerds TA, et al. pec: Prediction Error Curves for Survival Models.

See Also

predict_selectcox(), tune_selectcox(), pec::selectCox()

Examples

mod <- fit_selectcox(Surv(time, status) ~ age + celltype + karno, data = veteran)

Description

Fits a parametric/penalised generalised survival model using rstpm2's stpm2(), returning an mlsurv_model object that integrates with the survalis evaluation and cross‑validation pipeline. The baseline hazard is modeled with restricted cubic splines controlled by the degrees of freedom.

Usage

fit_stpm2(formula, data, df = 4, ...)

Arguments

Details

This wrapper standardizes the model object to the mlsurv_model contract so downstream prediction and evaluation behave consistently across learners.

Value

An object of class mlsurv_model, a named list with elements:

model

The fitted rstpm2::stpm2 object.

learner

Character scalar identifying the learner ("stpm2").

engine

Character scalar naming the engine ("rstpm2").

formula

The original survival formula.

data

The training dataset (or a minimal subset needed for prediction).

time

Name of the survival time variable.

status

Name of the event indicator (1 = event, 0 = censored).

Engine

Uses rstpm2::stpm2. Spline complexity is governed by df; larger values allow more flexibility in the baseline hazard. Additional engine arguments can be passed via ....

References

Royston P, Parmar MKB (2002). Flexible parametric proportional‑hazards and proportional‑odds models for censored survival data. Statistics in Medicine. Lambert PC, Royston P, Crowther MJ (2009). Restricted cubic splines for non‑proportional hazards. Statistics in Medicine.

Examples

mod_stpm2 <- fit_stpm2(Surv(time, status) ~ age + karno + celltype,
                       data = veteran, df = 4)
predict_stpm2(mod_stpm2, newdata = veteran[1:5, ], times = c(100, 200, 300))
summary(mod_stpm2)

Description

Fits a deep neural network survival model using survdnn (backed by torch). Supports the losses currently exposed by survdnn ("cox", "cox_l2", "aft", and "coxtime"). Returns an mlsurv_model object that integrates with the survalis evaluation and cross-validation pipeline.

Usage

fit_survdnn(
  formula,
  data,
  loss = "cox",
  hidden = c(32L, 32L, 16L),
  activation = "relu",
  lr = 1e-04,
  epochs = 300L,
  optimizer = "adam",
  optim_args = list(),
  verbose = FALSE,
  dropout = 0.3,
  batch_norm = TRUE,
  callbacks = NULL,
  .seed = NULL,
  .device = "auto",
  na_action = "omit",
  ...
)

Arguments

Details

Design contract. All ⁠fit_*()⁠ functions in survalis: (i) return a named list with model, learner, engine, formula, data, time, and status; and (ii) retain information required by ⁠predict_*()⁠ to build a consistent design for new data.

Value

An object of class mlsurv_model, a named list with elements:

model

The underlying fitted survdnn model.

learner

Character scalar identifying the learner ("survdnn").

engine

Character scalar naming the engine ("survdnn").

formula

The original survival formula.

data

The training dataset (or a minimal subset needed for prediction).

time

Name of the survival time variable.

status

Name of the event indicator (1 = event, 0 = censored).

Engine

Uses survdnn::survdnn with torch. The wrapper exposes the core training arguments used by the engine, including optimizer choice, dropout, batch normalization, callbacks, device selection, and missing-value handling.

References

survdnn documentation; torch for deep learning in R.

See Also

predict_survdnn(), tune_survdnn()

Examples

if (requireNamespace("survdnn", quietly = TRUE) &&
    requireNamespace("torch", quietly = TRUE) &&
    torch::torch_is_installed()) {
  mod <- fit_survdnn(Surv(time, status) ~ age + karno + celltype,
                     data = veteran, loss = "cox", epochs = 50, verbose = FALSE)

  pred <- predict_survdnn(mod, newdata = veteran[1:5, ], times = c(30, 90, 180))
  print(pred)
}

Description

Learns nonnegative, time‑specific stacking weights over a set of base survival learners by solving a nonnegative least squares (NNLS) problem at each requested time $t^{*}$. For each $t^{*}$, the target is the indicator $Y = I(T > t^{*})$; the features are the base learners' predicted survival probabilities $S_\ell(t^{*} \mid x)$. Weights are constrained to be nonnegative and are normalized to sum to 1 per time point.

Usage

fit_survmetalearner(
  base_preds,
  time,
  status,
  times,
  base_models,
  formula,
  data
)

Arguments

Details

For each t in times, this function fits

$\min_{w \ge 0} \\mid Y - S w \|_2^2 \quad \text{s.t.} \ \sum_j w_j = 1$

where $Y = I(T > t)$ and $S$ is the matrix of base survival probabilities at $t$. The NNLS solution from nnls is renormalized to sum to 1 (if the solution is all zeros, weights remain NA for that time).

Value

An object of class c("mlsurv_model","survmetalearner") with elements:

weights

Matrix L x T of nonnegative stacking weights, rows=learners, cols="t=<time>".

base_models

Named list of base learner fits.

base_preds

Named list of base prediction matrices on training data.

learners

Character vector of learner names (from names(base_preds)).

formula, data, time, status

Training metadata for scoring/reporting.

learner

The string "survmetalearner" (for predict_* dispatch).

See Also

predict_survmetalearner, plot_survmetalearner_weights, cv_survmetalearner

Examples

form <- Surv(time, status) ~ age + karno + trt
times <- c(80, 160)
mod_cox <- fit_coxph(form, data = veteran)
mod_rpart <- fit_rpart(form, data = veteran)
base_models <- list(coxph = mod_cox, rpart = mod_rpart)
base_preds <- list(
  coxph = predict_coxph(mod_cox, newdata = veteran, times = times),
  rpart = predict_rpart(mod_rpart, newdata = veteran, times = times)
)
meta_model <- fit_survmetalearner(
  base_preds = base_preds,
  time = veteran$time,
  status = veteran$status,
  times = times,
  base_models = base_models,
  formula = form,
  data = veteran
)
meta_model$weights

Description

Fits a survival support vector machine using survivalsvm. The default setup uses the regression-type loss with quadratic programming optimization and an additive or linear kernel, but all survivalsvm options are exposed. Returns an mlsurv_model object that integrates with the survalis evaluation and cross-validation pipeline.

Usage

fit_survsvm(
  formula,
  data,
  type = "regression",
  gamma.mu = 0.1,
  opt.meth = "quadprog",
  kernel = "add_kernel",
  diff.meth = NULL
)

Arguments

Details

Design contract. All ⁠fit_*()⁠ functions in survalis: (i) return a named list with model, learner, engine, formula, data, time, and status; (ii) preserve terms(formula) or equivalent for consistent prediction design; and (iii) keep engine arguments required downstream by ⁠predict_*()⁠.

Value

An object of class mlsurv_model, a named list with elements:

model

The underlying fitted survivalsvm model.

learner

Character scalar identifying the learner ("survsvm").

engine

Character scalar naming the engine ("survivalsvm").

formula

The original survival formula.

data

The training dataset (or a minimal subset needed for prediction).

time

Name of the survival time variable.

status

Name of the event indicator (1 = event, 0 = censored).

Engine

Uses survivalsvm::survivalsvm. Some optimization methods (e.g., "quadprog") require additional system dependencies and the quadprog package to be installed.

References

Binder H, et al. (2009). Survival Support Vector Machines (and related work). survivalsvm package documentation.

See Also

predict_survsvm(), tune_survsvm()

Examples

mod_svm <- fit_survsvm(Surv(time, status) ~ age + celltype + karno,
                           data = veteran,
                           type = "regression",
                           gamma.mu = 0.1,
                           kernel = "lin_kernel")

times <- c(100, 300, 500)
predict_survsvm(mod_svm, newdata = veteran[1:5, ], times = times, dist = "exp")
predict_survsvm(mod_svm, newdata = veteran[1:5, ], times = times, dist = "weibull", shape = 1.5)

cv_results_svm <- cv_survlearner(
  formula = Surv(time, status) ~ age + celltype + karno,
  data = veteran,
  fit_fun = fit_survsvm,
  pred_fun = predict_survsvm,
  times = c(100, 300, 500),
  metrics = c("cindex", "ibs"),
  folds = 5,
  seed = 42,
  gamma.mu = 0.1,
  kernel = "lin_kernel")

print(cv_results_svm)
cv_summary(cv_results_svm)
cv_plot(cv_results_svm)

Description

Fits a gradient-boosted tree model for time-to-event outcomes using xgboost. Supports "survival:aft" (default) and "survival:cox". Returns an mlsurv_model object compatible with the survalis pipeline.

Usage

fit_xgboost(
  formula,
  data,
  booster = "gbtree",
  objective = "survival:aft",
  aft_loss_distribution = "extreme",
  aft_loss_distribution_scale = 1,
  nrounds = 100
)

Arguments

Details

Design contract: returns a named list with engine metadata and preserves terms(formula) so prediction uses the exact same encoding as training.

Value

An object of class mlsurv_model:

model

Fitted xgboost model.

learner

"xgboost".

formula, data

Original inputs.

time, status

Names of the survival time and event variables.

objective

Objective used.

dist, scale

AFT distribution and scale (populated even if Cox is used).

terms

Preserved terms for consistent prediction design matrices.

Engine

Uses xgboost. For "survival:aft", interval labels are set via label_lower_bound/label_upper_bound with right-censoring represented by Inf on the upper bound. For "survival:cox", labels follow the Cox objective convention.

See Also

predict_xgboost(), tune_xgboost()

Examples

mod_xgb <- fit_xgboost(
    Surv(time, status) ~ age + karno + celltype,
    data = veteran
  )

Description

Computes $\int \mid \bar{S}(t) - \hat{S}_{KM}(t) \mid \, dt$ where $\bar{S}(t)$ is the mean predicted survival across subjects and $\hat{S}_{KM}(t)$ is the Kaplan-Meier estimate. Integration is carried out over KM event times using a left Riemann sum.

Usage

iae_survmat(object, sp_matrix, times)

Arguments

Value

A named numeric scalar: "iae".

Examples

y <- survival::Surv(time = veteran$time, event = veteran$status)
times <- c(60, 120)
lp <- stats::plogis(scale(veteran$karno))
sp <- cbind("t=60" = pmin(1, lp + 0.05), "t=120" = pmax(0, lp - 0.05))
colnames(sp) <- c("t=60", "t=120")
iae_survmat(y, sp_matrix = sp, times = times)

Description

Computes the Integrated Brier Score (IBS) over a vector of times, using discrete left Riemann integration of IPCW Brier scores.

Usage

ibs_survmat(object, sp_matrix, times)

Arguments

Value

A named numeric scalar: "ibs".

Examples

y <- survival::Surv(time = veteran$time, event = veteran$status)
times <- c(60, 120)
lp <- stats::plogis(scale(veteran$karno))
sp <- cbind("t=60" = pmin(1, lp + 0.05), "t=120" = pmax(0, lp - 0.05))
colnames(sp) <- c("t=60", "t=120")
ibs_survmat(y, sp_matrix = sp, times = times)

Description

Computes $\int ( \bar{S}(t) - \hat{S}_{KM}(t) )^2 \, dt$ where $\bar{S}(t)$ is the mean predicted survival and $\hat{S}_{KM}(t)$ is the Kaplan-Meier curve. Integration uses KM event times and a left Riemann sum.

Usage

ise_survmat(object, sp_matrix, times)

Arguments

Value

A named numeric scalar: "ise".

Examples

y <- survival::Surv(time = veteran$time, event = veteran$status)
times <- c(60, 120)
lp <- stats::plogis(scale(veteran$karno))
sp <- cbind("t=60" = pmin(1, lp + 0.05), "t=120" = pmax(0, lp - 0.05))
colnames(sp) <- c("t=60", "t=120")
ise_survmat(y, sp_matrix = sp, times = times)

Description

Returns a table mapping each compute_* function to its paired plot_* helper (if any). Methods without a plot helper show NA.

Usage

list_interpretability_methods()

Value

A tibble with columns compute, plot, has_compute, and has_plot.

Examples

list_interpretability_methods()
subset(list_interpretability_methods(), is.na(plot))  # methods without plot

Description

Returns a data frame describing the evaluation metrics supported by survalis (as used by helpers like cv_survlearner() and score_survmodel()).

Usage

list_metrics()

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.

Value

A tibble/data.frame with one row per metric.

Examples

list_metrics()

Description

Returns a table of known survival learners, showing the expected ⁠fit_*⁠, ⁠predict_*⁠, and (if present) ⁠tune_*⁠ functions, plus booleans indicating which functions are available.

Usage

list_survlearners(has_tune = FALSE)

Arguments

Value

A tibble with columns:

• learner – learner id (e.g., "ranger")

• fit, predict, tune – function names (tune may be NA)

• has_fit, has_predict, has_tune – logical flags

• available – has_fit & has_predict

Examples

list_survlearners()                   # all learners (default)
list_survlearners(has_tune = TRUE)    # only tunable learners

Description

Filters learners to only those that provide a ⁠tune_*⁠ function in addition to ⁠fit_*⁠ and ⁠predict_*⁠.

Usage

list_tunable_survlearners()

Value

A base data.frame like list_survlearners() but containing only rows where tune is not NA.

Examples

list_tunable_survlearners()

Description

Visualizes ALE results produced by compute_ale() either as per-time curves (one curve per evaluation time) or as an integrated curve averaged across times.

Usage

plot_ale(
  ale_result,
  feature,
  which = c("per_time", "integrated"),
  smooth = FALSE
)

Arguments

Details

Per-time plots show how the feature's local effect varies across different evaluation times. The integrated plot summarizes the average effect over the supplied time grid (simple mean across times of the centered ALE values).

Value

A ggplot2 object.

See Also

compute_ale(), compute_pdp(), plot_pdp()

Examples

mod <- fit_coxph(Surv(time, status) ~ age + karno + celltype, data = veteran)
ale_res <- compute_ale(
  model = mod,
  newdata = veteran,
  feature = "karno",
  times = c(80, 160),
  grid.size = 8
)
plot_ale(ale_res, feature = "karno", which = "per_time")
plot_ale(ale_res, feature = "karno", which = "integrated", smooth = TRUE)

Description

Produces box‑and‑jitter plots of CV metric values per learner, faceted by metric for quick visual comparison.

Usage

plot_benchmark(benchmark_results)

Arguments

Value

A ggplot2 object.

See Also

benchmark_default_survlearners(), summarise_benchmark()

Examples

res <- tibble::tibble(
  learner = c("coxph", "coxph", "rpart", "rpart"),
  metric = c("cindex", "ibs", "cindex", "ibs"),
  value = c(0.64, 0.19, 0.60, 0.23)
)
plot_benchmark(res)

Description

Produces a calibration plot comparing mean predicted survival (x-axis) to observed survival with bootstrap CIs (y-axis) at a single evaluation time.

Usage

plot_calibration(calib_output, smooth = TRUE)

Arguments

Details

Points above the diagonal indicate underprediction (observed survival higher than predicted), while points below indicate overprediction.

Value

A ggplot2 object showing bin-wise calibration points, bootstrap error bars, the 45° reference line, and (optionally) a smooth curve.

See Also

compute_calibration()

Examples

mod <- fit_coxph(Surv(time, status) ~ age + karno + celltype, data = veteran)
calib <- compute_calibration(
  model = mod,
  data = veteran,
  time = "time",
  status = "status",
  eval_time = 80,
  n_bins = 4,
  n_boot = 5,
  seed = 1
)
plot_calibration(calib)

Description

Visualizes counterfactual feature changes returned by compute_counterfactual, ranking recommendations by either raw survival gain or penalized gain.

Usage

plot_counterfactual(
  counterfactual_df,
  metric = c("penalized_gain", "survival_gain"),
  top_n = NULL,
  include_negative = FALSE
)

Arguments

Value

A ggplot2 object.

Examples

df <- veteran
df$A <- df$trt
mod <- fit_coxph(survival::Surv(time, status) ~ A + age + karno, data = df)
cf <- compute_counterfactual(
  model = mod,
  newdata = df[1, , drop = FALSE],
  times = c(50, 100, 150),
  target_time = 100,
  features_to_change = c("A", "age", "karno"),
  grid.size = 10
)
plot_counterfactual(cf)

Description

Visualizes interaction outputs from compute_interactions as (i) a ranked bar chart for one-way interactions, (ii) a pairwise heatmap, or (iii) time-varying interaction trajectories.

Usage

plot_interactions(object, type = c("1way", "heatmap", "time"))

Arguments

Details

1way: Bars rank features by Friedman-H interaction strength at the target time. heatmap: Tiles show pairwise interaction magnitudes (symmetric). time: Lines show interaction strength vs. time for each feature.

Value

A ggplot2 object.

Examples

mod <- fit_coxph(Surv(time, status) ~ age + karno + trt, data = veteran)
times <- c(80, 160)
ia <- compute_interactions(
  model = mod,
  data = veteran,
  times = times,
  target_time = 80,
  features = c("age", "karno"),
  type = "1way",
  grid.size = 6
)
plot_interactions(ia, type = "1way")

Description

Plots partial dependence (PDP) and/or individual conditional expectation (ICE) results returned by compute_pdp either per evaluation time or as an integrated PDP over time.

Usage

plot_pdp(
  pdp_ice_output,
  feature,
  method = "pdp+ice",
  ids = NULL,
  which = c("per_time", "integrated"),
  alpha_ice = 0.2,
  smooth = FALSE
)

Arguments

Details

Per-time: For numeric features, draws ICE lines and PDP overlays per time. For categorical features, shows ICE as boxplots per level and PDP as point summaries. Integrated: Plots the PDP integrated across time (if provided by compute_pdp()); numeric features can be smoothed with smooth=TRUE.

Value

A ggplot2 object.

Examples

mod <- fit_coxph(Surv(time, status) ~ age + karno + trt, data = veteran)
pdp_age <- compute_pdp(
  model = mod,
  data = veteran,
  feature = "age",
  times = c(80, 160),
  method = "pdp+ice",
  grid.size = 8
)
plot_pdp(pdp_age, feature = "age", which = "per_time")
plot_pdp(pdp_age, feature = "age", which = "integrated", smooth = TRUE)

Description

Plots time-dependent SHAP estimates (lines over time) or aggregated SHAP (bar chart) returned by compute_shap().

Usage

plot_shap(shapley_result, type = c("auto"))

Arguments

Value

A ggplot2 object.

Examples

mod <- fit_coxph(survival::Surv(time, status) ~ age + karno + celltype, data = veteran)
shap_td <- compute_shap(mod, veteran[10, , drop = FALSE],
veteran, times = c(50, 100), sample.size = 5)
p1 <- plot_shap(shap_td)      # auto -> time plot

shap_ag <- compute_shap(mod, veteran[10, , drop = FALSE],
veteran, times = c(50, 100),
sample.size = 5, aggregate = TRUE, method = "meanabs")
p2 <- plot_shap(shap_ag)      # auto -> bar plot

Description

Visualizes the signed local effects from compute_surrogate as a horizontal bar chart, optionally limiting to the top n contributors.

Usage

plot_surrogate(surrogate_df, top_n = NULL)

Arguments

Value

A ggplot2 object showing feature contributions $\beta_j \cdot x_j$ (positive/negative) at the target time.

Examples

mod <- fit_coxph(Surv(time, status) ~ age + karno + celltype, data = veteran)
local_expl <- compute_surrogate(
  model = mod,
  newdata = veteran[2, , drop = FALSE],
  baseline_data = veteran,
  times = c(80, 160),
  target_time = 80,
  k = 3
)
plot_surrogate(local_expl, top_n = 3)

Description

Plots one or more predicted survival curves from a survival-probability matrix. By default, each row of S is shown as an individual curve. If a group vector is supplied, curves are summarized by group using the requested aggregation function.