unsurv_stability: Stability assessment for an unsurv clustering

In unsurv: Unsupervised Clustering of Individualized Survival Curves

Stability assessment for an unsurv clustering

Description

Computes a resampling-based stability score for a fitted unsurv model using the Adjusted Rand Index (ARI) computed on overlap sets across resamples.

Usage

unsurv_stability(
  S,
  times,
  fit,
  B = 30,
  frac = 0.5,
  mode = c("bootstrap", "subsample"),
  jitter_sd = 0.01,
  weight_perturb = 0.3,
  eps_jitter = 0.02,
  return_distribution = TRUE
)

Arguments

S	Numeric matrix of survival probabilities used for stability assessment (n \times m), with columns matching times.
times	Numeric vector of time grid points (length m).
fit	An object of class "unsurv", typically returned by unsurv.
B	Integer; number of resamples.
frac	Numeric in (0, 1]; fraction of rows sampled per resample.
mode	Resampling mode: "bootstrap" (with replacement) or "subsample" (without replacement).
jitter_sd	Nonnegative numeric; curve-space noise level applied before clamping/monotone enforcement.
weight_perturb	Numeric in [0,1]; blends trapezoidal weights with a random simplex to perturb the weighting scheme.
eps_jitter	Nonnegative numeric; feature-space jitter used inside the clustering during resamples.
return_distribution	Logical; if TRUE, returns the full ARI distribution, else returns only the mean.

Value

If return_distribution = TRUE, a list with:

• mean: mean ARI across resample-pair overlaps

• aris: numeric vector of ARIs

Otherwise, returns a single numeric mean ARI.

Examples

if (requireNamespace("cluster", quietly = TRUE)) {
  set.seed(2025)
  n <- 60; Q <- 40
  times <- seq(0, 5, length.out = Q)
  rates <- c(0.12, 0.38, 0.8)
  grp <- sample(1:3, n, TRUE, c(0.4, 0.4, 0.2))
  S <- t(vapply(1:n, function(i)
    pmin(pmax(exp(-rates[grp[i]] * times) + rnorm(Q, 0, 0.01), 0), 1),
    numeric(Q)
  ))

  fit <- unsurv(S, times, K = NULL, K_max = 6, distance = "L2",
               enforce_monotone = TRUE, standardize_cols = FALSE,
               eps_jitter = 0, seed = NULL)

  stab <- unsurv_stability(S, times, fit, B = 8, frac = 0.55, mode = "bootstrap",
                           jitter_sd = 0.3, weight_perturb = 0.0, eps_jitter = 0.3,
                           return_distribution = TRUE)
  stab$mean
}

unsurv documentation built on Sept. 1, 2026, 1:06 a.m.