Package {nbsurv}

Calibration Plot for a nbsurv Model

Description

Assesses calibration of a nbsurv model at a single prediction horizon by grouping observations into quantile bins of predicted event probability and comparing the group mean prediction against the Kaplan-Meier observed event probability within each bin.

Usage

calibration_plot_nbsurv(object, newdata, horizon, n_groups = 10, ...)

Arguments

Value

Invisibly returns a data frame with columns mean_pred (mean predicted event probability per group), observed (observed event probability from Kaplan-Meier), and n (group size). The calibration plot is drawn as a side effect.

Examples

library(survival)

lung <- stats::na.omit(lung)
lung$status <- as.integer(lung$status == 2)
fit <- nbsurv(Surv(time, status) ~ age + sex, data = lung)
calibration_plot_nbsurv(fit, newdata = lung, horizon = 300)

Evaluate, Cross-Validate, and Tune nbsurv Models

Description

Provides resampling-based utilities for evaluating, cross-validating, and tuning nbsurv survival models using horizon-specific Brier score, integrated Brier score (IBS), and concordance.

The integrated Brier score summarises calibration over a range of horizons:

\mathrm{IBS} = \frac{1}{\tau - t_1} \int_{t_1}^{\tau} \mathrm{BS}(t)\, dt

approximated by the trapezoidal rule over the supplied times.

Usage

cv_nbsurv(
  formula,
  data,
  folds = 5,
  times = NULL,
  seed = NULL,
  scale = TRUE,
  laplace = 1,
  min_sd = 0.05,
  time_grid = NULL,
  eps = 1e-06,
  cov_structure = c("diagonal", "full"),
  shrinkage = 0.2,
  time_smooth = FALSE,
  bandwidth = NULL
)

evaluate_nbsurv(object, newdata, times, metrics = c("brier", "concordance"), ibs = FALSE)

tune_nbsurv(
  formula,
  data,
  param_grid,
  folds = 5,
  times = NULL,
  metric = c("brier", "concordance"),
  maximize = NULL,
  seed = NULL,
  eps = 1e-06
)

Arguments

Value

evaluate_nbsurv() returns a data frame of horizon-specific metrics. When ibs = TRUE the integrated Brier score is attached via attr(result, "ibs"). cv_nbsurv() returns a list with fold-level and mean cross-validation summaries. tune_nbsurv() returns a list with all candidate results and the best row.

Examples

library(survival)

lung <- stats::na.omit(lung)
lung$status <- as.integer(lung$status == 2)
fit <- nbsurv(Surv(time, status) ~ age + sex, data = lung)
res <- evaluate_nbsurv(fit, newdata = lung[1:50, ], times = c(100, 200, 400), ibs = TRUE)
res
attr(res, "ibs")

cv_nbsurv(Surv(time, status) ~ age + sex, data = lung, folds = 3, times = c(100, 200))

Fit a Conditional Naive Bayes Survival Model

Description

Fits a conditional naive Bayes model for right-censored survival data. The model combines the marginal Kaplan-Meier survival estimate with horizon-specific likelihood terms estimated among subjects who fail before the horizon and subjects known to survive beyond it.

Usage

nbsurv(
  formula,
  data,
  scale = TRUE,
  laplace = 1,
  min_sd = 0.05,
  time_grid = NULL,
  eps = 1e-06,
  cov_structure = c("diagonal", "full"),
  shrinkage = 0.2,
  time_smooth = FALSE,
  bandwidth = NULL
)

Arguments

Value

An object of class "nbsurv".

Examples

library(survival)

lung <- stats::na.omit(lung)
lung$status <- as.integer(lung$status == 2)
fit <- nbsurv(
  Surv(time, status) ~ age + sex,
  data = lung
)

predict(fit, newdata = lung[1:3, ], times = c(100, 200, 300))

Conditional Naive Bayes Survival Model Object

Description

nbsurv objects are created by nbsurv and store the training data, outcome, feature types, scaling information, and the Kaplan-Meier estimates required for prediction.

Usage

## S3 method for class 'nbsurv'
print(x, ...)

## S3 method for class 'nbsurv'
plot(x, times = NULL, n_curves = 5, ...)

Arguments

Value

print.nbsurv is called for its side effect of printing a concise summary of the fitted model (formula, number of training rows, predictors, prediction grid size, covariance structure, and time-smoothing settings) to the console; it returns its argument x invisibly.

plot.nbsurv is called for its side effect of drawing predicted survival curves for the first n_curves training observations over times; it returns, invisibly, the matrix of predicted survival probabilities used for the plot (one row per displayed observation, one column per element of times).

Visualization Helpers for nbsurv Results

Description

Base-graphics plot methods for the result objects returned by varimp_nbsurv, cv_nbsurv, and tune_nbsurv.

plot.varimp_nbsurv() draws a horizontal bar chart of permutation importance, sorted by increasing importance (largest bar at top).

plot.cv_nbsurv() draws the mean cross-validation metric against the evaluation horizons.

plot.tune_nbsurv() draws the mean tuning metric for every candidate row of param_grid, highlighting the selected best candidate in red.

Usage

## S3 method for class 'varimp_nbsurv'
plot(x, ...)

## S3 method for class 'cv_nbsurv'
plot(x, metric = c("brier", "concordance"), ...)

## S3 method for class 'tune_nbsurv'
plot(x, ...)

Arguments

Value

The input object, invisibly. Called for its plotting side effect.

Examples

library(survival)

lung <- stats::na.omit(lung)
lung$status <- as.integer(lung$status == 2)
fit <- nbsurv(Surv(time, status) ~ age + sex + ph.ecog, data = lung)

vi <- varimp_nbsurv(fit, newdata = lung, times = c(100, 200, 400), n_repeats = 5, seed = 1)
plot(vi)

cvfit <- cv_nbsurv(Surv(time, status) ~ age + sex, data = lung, folds = 3, times = c(100, 200, 300))
plot(cvfit)

grid <- expand.grid(scale = TRUE, laplace = c(0.5, 1, 2), min_sd = 0.05)
tf <- tune_nbsurv(
  Surv(time, status) ~ age + sex, data = lung,
  param_grid = grid, folds = 3, times = c(100, 200)
)
plot(tf)

Predict Survival Probabilities from a nbsurv Model

Description

Computes horizon-specific survival or event probabilities from a fitted conditional naive Bayes survival model. The returned survival curves are forced to be non-increasing across increasing time horizons.

Usage

## S3 method for class 'nbsurv'
predict(object, newdata, times, type = c("survival", "event"), ...)

predictSurvProb(object, ...)

## S3 method for class 'nbsurv'
predictSurvProb(object, newdata, times, ...)

Arguments

Value

A matrix with one row per observation in newdata and one column per prediction horizon.

Examples

library(survival)

lung <- stats::na.omit(lung)
lung$status <- as.integer(lung$status == 2)
fit <- nbsurv(Surv(time, status) ~ age + sex, data = lung)
predict(fit, newdata = lung[1:2, ], times = c(100, 200))
predict(fit, newdata = lung[1:2, ], times = c(100, 200), type = "event")

Permutation Variable Importance for nbsurv Models

Description

Computes permutation-based variable importance: for each predictor, its values are independently shuffled n_repeats times, evaluate_nbsurv is recomputed on the permuted data, and importance is the resulting degradation in the chosen metric, averaged over times and repeats. Predictors the model relies on more heavily degrade performance more when permuted.

Usage

varimp_nbsurv(
  object,
  newdata,
  times,
  metric = c("brier", "concordance"),
  n_repeats = 10,
  seed = NULL
)

Arguments

Value

A data frame (class "varimp_nbsurv") with one row per predictor, sorted by decreasing importance, with columns feature, baseline (the unpermuted metric, averaged over times), permuted (the metric after permuting that feature, averaged over times and n_repeats), and importance (the degradation: permuted - baseline for "brier", baseline - permuted for "concordance", so higher is always more important).

Examples

library(survival)

lung <- stats::na.omit(lung)
lung$status <- as.integer(lung$status == 2)
fit <- nbsurv(Surv(time, status) ~ age + sex + ph.ecog, data = lung)
varimp_nbsurv(fit, newdata = lung, times = c(100, 200, 400), n_repeats = 5, seed = 1)