Brier Score for Right-Censored Survival Data at a Fixed Time

Description

Computes the Brier score at a fixed time point using inverse probability of censoring weights (IPCW).

Usage

brier(object, pre_sp, t_star)

Arguments

Value

A single numeric value representing the Brier score.

Examples

library(survival)
data(veteran, package = "survival")
mod <- survdnn(Surv(time, status) ~
age + karno + celltype, data = veteran, epochs = 50, verbose = FALSE)
pred <- predict(mod, newdata = veteran, type = "survival", times = c(30, 90, 180))
y <- model.response(model.frame(mod$formula, veteran))
survdnn::brier(y, pre_sp = pred[["t=90"]], t_star = 90)

Build a Deep Neural Network for Survival Analysis

Description

Constructs a multilayer perceptron (MLP) with optional batch normalization and dropout. Used internally by [survdnn()] to define the model architecture.

Usage

build_dnn(
  input_dim,
  hidden,
  activation = "relu",
  output_dim = 1L,
  dropout = 0.3,
  batch_norm = TRUE
)

Arguments

Value

A 'nn_sequential' object representing the network.

Early stopping callback for survdnn

Description

Simple early stopping on a monitored scalar, typically the training loss.

Usage

callback_early_stopping(
  patience = 10L,
  min_delta = 0,
  mode = c("min", "max"),
  verbose = FALSE
)

Arguments

Value

A function of the form 'function(epoch, current)' that returns TRUE if training should stop, FALSE otherwise.

Concordance Index from a Survival Probability Matrix

Description

Computes the time-dependent concordance index (C-index) from a predicted survival matrix at a fixed time point. The risk is computed as '1 - S(t_star)'.

Usage

cindex_survmat(object, predicted, t_star = NULL)

Arguments

Value

A single numeric value representing the C-index.

Examples

library(survival)
data(veteran, package = "survival")
mod <- survdnn(Surv(time, status) ~
age + karno + celltype, data = veteran, epochs = 50, verbose = FALSE)
pred <- predict(mod, newdata = veteran, type = "survival", times = c(30, 90, 180))
y <- model.response(model.frame(mod$formula, veteran))
cindex_survmat(y, pred, t_star = 180)

K-Fold Cross-Validation for survdnn Models

Description

Performs cross-validation for a 'survdnn' model using the specified evaluation metrics.

Usage

cv_survdnn(
  formula,
  data,
  times,
  metrics = c("cindex", "ibs"),
  folds = 5,
  .seed = NULL,
  .device = c("auto", "cpu", "cuda"),
  na_action = c("omit", "fail"),
  ...
)

Arguments

Value

A tibble containing metric values per fold and (optionally) per time point.

Examples

library(survival)
data(veteran)
cv_survdnn(
  Surv(time, status) ~ age + karno + celltype,
  data = veteran,
  times = c(30, 90, 180),
  metrics = "ibs",
  folds = 3,
  .seed = 42,
  hidden = c(16, 8),
  epochs = 5
)

Evaluate a survdnn Model Using Survival Metrics

Description

Computes evaluation metrics for a fitted 'survdnn' model at one or more time points. Supported metrics include the concordance index ('"cindex"'), Brier score ('"brier"'), and integrated Brier score ('"ibs"').

Usage

evaluate_survdnn(
  model,
  metrics = c("cindex", "brier", "ibs"),
  times,
  newdata = NULL,
  na_action = c("omit", "fail"),
  verbose = FALSE
)

Arguments

Value

A tibble with evaluation results, containing at least 'metric', 'value', and possibly 'time'.

Grid Search for survdnn Hyperparameters

Description

Performs grid search over user-specified hyperparameters and evaluates performance on a validation set.

Usage

gridsearch_survdnn(
  formula,
  train,
  valid,
  times,
  metrics = c("cindex", "ibs"),
  param_grid,
  .seed = 42,
  .device = c("auto", "cpu", "cuda")
)

Arguments

Value

A tibble with configurations and their validation metrics

Examples

library(survdnn)
library(survival)
set.seed(123)
# Simulate small dataset
n <- 300
x1 <- rnorm(n); x2 <- rbinom(n, 1, 0.5)
time <- rexp(n, rate = 0.1)
status <- rbinom(n, 1, 0.7)
df <- data.frame(time, status, x1, x2)
# Split into training and validation
idx <- sample(seq_len(n), 0.7 * n)
train <- df[idx, ]
valid <- df[-idx, ]
# Define formula and param grid
formula <- Surv(time, status) ~ x1 + x2
param_grid <- list(
  hidden     = list(c(16, 8), c(32, 16)),
  lr         = c(1e-3),
  activation = c("relu"),
  epochs     = c(100),
  loss       = c("cox", "coxtime")
)
# Run grid search
results <- gridsearch_survdnn(
  formula = formula,
  train   = train,
  valid   = valid,
  times   = c(10, 20, 30),
  metrics = c("cindex", "ibs"),
  param_grid = param_grid
)
# View summary
dplyr::group_by(results, hidden, lr, activation, epochs, loss, metric) |>
  dplyr::summarise(mean = mean(value, na.rm = TRUE), .groups = "drop")

Integrated Brier Score (IBS) from a Survival Probability Matrix

Description

Computes the Integrated Brier Score (IBS) over a set of evaluation time points, using trapezoidal integration and IPCW adjustment for right-censoring.

Usage

ibs_survmat(object, sp_matrix, times)

Arguments

Value

A single numeric value representing the integrated Brier score.

Examples

set.seed(123)
library(survival)
data(veteran, package = "survival")
idx <- sample(nrow(veteran), 0.7 * nrow(veteran))
train <- veteran[idx, ]; test <- veteran[-idx, ]
mod <- survdnn(Surv(time, status) ~
age + karno + celltype, data = train, epochs = 50, verbose = FALSE)
pred <- predict(mod, newdata = test, times = c(30, 90, 180), type = "survival")
y_test <- model.response(model.frame(mod$formula, test))
ibs_survmat(y_test, sp_matrix = pred, times = c(30, 90, 180))

Plot survdnn Survival Curves using ggplot2

Description

Visualizes survival curves predicted by a fitted 'survdnn' model. Curves can be grouped by a categorical variable in 'newdata' and optionally display only the group-wise means or overlay them.

Usage

## S3 method for class 'survdnn'
plot(
  x,
  newdata = NULL,
  times = 1:365,
  group_by = NULL,
  plot_mean_only = FALSE,
  add_mean = TRUE,
  alpha = 0.3,
  mean_lwd = 1.3,
  mean_lty = 1,
  ...
)

Arguments

Value

A 'ggplot' object.

Examples

library(survival)
data(veteran)
set.seed(42)

mod <- survdnn(Surv(time, status) ~ age + karno + celltype, data = veteran,
               hidden = c(16, 8), epochs = 100, verbose = FALSE)
plot(mod, group_by = "celltype", times = 1:300)

Plot Training Loss for a survdnn Model

Description

Visualize the evolution of the training loss across epochs for a fitted 'survdnn' model. Helps inspect convergence, instability, or callback effects (e.g., early stopping).

Usage

plot_loss(object, smooth = FALSE, log_y = FALSE, ...)

Arguments

Value

A 'ggplot' object.

Predict from a survdnn Model

Description

Generate predictions from a fitted 'survdnn' model for new data. Supports linear predictors, survival probabilities at specified time points, or cumulative risk estimates.

Usage

## S3 method for class 'survdnn'
predict(object, newdata, times = NULL, type = c("survival", "lp", "risk"), ...)

Arguments

Value

A numeric vector (if 'type = "lp"' or '"risk"'), or a data frame (if 'type = "survival"') with one row per observation and one column per 'times'.

Examples

library(survival)
data(veteran, package = "survival")

mod <- survdnn(
  Surv(time, status) ~ age + karno + celltype,
  data = veteran,
  loss = "cox",
  epochs = 50,
  verbose = FALSE
)

predict(mod, newdata = veteran, type = "lp")[1:5]
predict(mod, newdata = veteran, type = "survival", times = c(30, 90, 180))[1:5, ]
predict(mod, newdata = veteran, type = "risk", times = 180)[1:5]

Print a survdnn Model

Description

Pretty prints a fitted 'survdnn' model. Displays the formula, network architecture, training configuration, and final training loss.

Usage

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

Arguments

Value

The model object, invisibly.

Examples

library(survival)
data(veteran, package = "survival")
mod <- survdnn(Surv(time, status) ~
age + karno + celltype, data = veteran, epochs = 20, verbose = FALSE)
print(mod)

Summarize Cross-Validation Results from survdnn

Description

Computes mean, standard deviation, and confidence intervals for metrics from cross-validation.

Usage

summarize_cv_survdnn(cv_results, by_time = TRUE, conf_level = 0.95)

Arguments

Value

A tibble summarizing mean, sd, and confidence bounds per metric (and per time if applicable).

Examples

library(survival)
data(veteran)
res <- cv_survdnn(
  Surv(time, status) ~ age + karno + celltype,
  data = veteran,
  times = c(30, 90, 180, 270),
  metrics = c("cindex", "ibs"),
  folds = 3,
  .seed = 42,
  hidden = c(16, 8),
  epochs = 5
)
summarize_cv_survdnn(res)

Summarize survdnn Tuning Results

Description

Aggregates cross-validation results from 'tune_survdnn(return = "all")' by configuration, metric, and optionally by time point.

Usage

summarize_tune_survdnn(tuning_results, by_time = TRUE)

Arguments

Value

A summarized tibble with mean and standard deviation of performance metrics.

Summarize a Deep Survival Neural Network Model

Description

Provides a structured summary of a fitted 'survdnn' model, including the network architecture, training configuration, and data characteristics. The summary is printed automatically with a styled header and sectioned output using {cli} and base formatting. The object is returned invisibly.

Usage

## S3 method for class 'survdnn'
summary(object, ...)

Arguments

Value

Invisibly returns an object of class '"summary.survdnn"'.

Examples

set.seed(42)
sim_data <- data.frame(
  age = rnorm(100, 60, 10),
  sex = factor(sample(c("male", "female"), 100, TRUE)),
  trt = factor(sample(c("A", "B"), 100, TRUE)),
  time = rexp(100, 0.05),
  status = rbinom(100, 1, 0.7)
)
mod <- survdnn(Surv(time, status) ~ age + sex + trt, data = sim_data, epochs = 50, verbose = FALSE)
summary(mod)

Fit a Deep Neural Network for Survival Analysis

Description

Trains a deep neural network (DNN) to model right-censored survival data using one of the predefined loss functions: Cox, AFT, or Coxtime.

Usage

survdnn(
  formula,
  data,
  hidden = c(32L, 16L),
  activation = "relu",
  lr = 1e-04,
  epochs = 300L,
  loss = c("cox", "cox_l2", "aft", "coxtime"),
  optimizer = c("adam", "adamw", "sgd", "rmsprop", "adagrad"),
  optim_args = list(),
  verbose = TRUE,
  dropout = 0.3,
  batch_norm = TRUE,
  callbacks = NULL,
  .seed = NULL,
  .device = c("auto", "cpu", "cuda"),
  na_action = c("omit", "fail")
)

Arguments

Value

An object of class '"survdnn"' containing:

model

Trained 'nn_module' object.

formula

Original survival formula.

data

Training data used for fitting.

xnames

Predictor variable names.

x_center

Column means of predictors.

x_scale

Column standard deviations of predictors.

loss_history

Vector of loss values per epoch.

final_loss

Final training loss.

loss

Loss function name used ("cox", "aft", etc.).

activation

Activation function used.

hidden

Hidden layer sizes.

lr

Learning rate.

epochs

Number of training epochs.

optimizer

Optimizer name used.

optim_args

List of optimizer arguments used.

device

Torch device used for training ('torch_device').

Loss Functions for survdnn Models

Description

These functions define various loss functions used internally by 'survdnn()' for training deep neural networks on right-censored survival data.

Usage

cox_loss(pred, true)

cox_l2_loss(pred, true, lambda = 1e-04)

aft_loss(pred, true)

coxtime_loss(pred, true)

Arguments

Value

A scalar 'torch_tensor' representing the loss value.

Supported Losses

- **Cox partial likelihood loss** ('cox_loss'): Negative partial log-likelihood used in proportional hazards modeling. - **L2-penalized Cox loss** ('cox_l2_loss'): Adds L2 regularization to the Cox loss. - **Accelerated Failure Time (AFT) loss** ('aft_loss'): Mean squared error between predicted and log-transformed event times, applied to uncensored observations only. - **CoxTime loss** ('coxtime_loss'): Implements the partial likelihood loss from Kvamme & Borgan (2019), used in Cox-Time models.

Examples

# Used internally by survdnn()

Tune Hyperparameters for a survdnn Model via Cross-Validation

Description

Performs k-fold cross-validation over a user-defined hyperparameter grid and selects the best configuration according to the specified evaluation metric.

Usage

tune_survdnn(
  formula,
  data,
  times,
  metrics = "cindex",
  param_grid,
  folds = 3,
  .seed = 42,
  .device = c("auto", "cpu", "cuda"),
  na_action = c("omit", "fail"),
  refit = FALSE,
  return = c("all", "summary", "best_model")
)

Arguments

Value

A tibble or model object depending on the 'return' value.