unsurv

unsurv provides tools for unsupervised clustering of individualized survival curves using a medoid-based (PAM) algorithm. It is designed for applications where each observation is represented by a full survival probability trajectory over time, such as:

survival model predictions
individualized survival curves from Cox or deep learning models
dynamic risk trajectories
multi-omics prognostic profiles

The package provides:

Medoid-based clustering of survival curves
Automatic selection of number of clusters via silhouette
Support for weighted L1 and L2 distances
Prediction of cluster membership for new curves
Stability assessment via resampling and Adjusted Rand Index
Visualization tools

Installation

From GitHub

install.packages("remotes")
remotes::install_github("ielbadisy/unsurv")

From CRAN (after submission)

install.packages("unsurv")

Overview

The core function is:

unsurv()

which clusters survival curves represented as an n × m matrix:

rows = individuals
columns = survival probabilities at time points

Example: Clustering survival curves

library(unsurv)
set.seed(123)
n <- 100
Q <- 50
times <- seq(0, 5, length.out = Q)
rates <- c(0.2, 0.5, 0.9)
group <- sample(1:3, n, TRUE)
S <- sapply(times, function(t)
  exp(-rates[group] * t)
)
S <- S + matrix(rnorm(n * Q, 0, 0.01), nrow = n)
S[S < 0] <- 0
S[S > 1] <- 1
fit <- unsurv(S, times, K = NULL, K_max = 6)
fit
#> unsurv (PAM) fit
#>   K:3
#>   distance:L2 silhouette_mean:0.915
#>   n:100 Q:50

Plot cluster medoids

plot(fit)

Each line represents the medoid survival curve for a cluster.

Predict cluster membership for new curves

predict(fit, S[1:5, ])
#> [1] 1 1 1 2 1

Stability assessment

Cluster stability can be evaluated using resampling:

stab <- unsurv_stability(
  S, times, fit,
  B = 20,
  frac = 0.7,
  mode = "subsample"
)
stab$mean
#> [1] 0.9384743

Higher values indicate more stable clustering.

Using ggplot visualization

library(ggplot2)
library(unsurv)
autoplot(fit)

Methodological details

Given survival curves: