Introduction to survPhenoStab

library(survPhenoStab)
#> Loading required package: mclust
#> Package 'mclust' version 6.1.3
#> Type 'citation("mclust")' for citing this R package in publications.

Overview

survPhenoStab implements the stability-driven hierarchical clustering framework for multi-endpoint patient phenotyping described in Roy Chowdhury et al., “A stability-driven hierarchical clustering framework for multi-endpoint patient phenotyping in oncology”. It provides:

A minimal simulated example

sim <- sim_competing_risks(n = 300, seed = 2024)
Z <- sim$embedding
dim(Z)
#> [1] 300   6

Fit and assess one configuration:

ca <- boot_jaccard(Z, distance = "cosine", linkage = "average", k = 3, B = 100, seed = 2024)
ca
#> Configuration: cosine distance, average linkage, K = 3 (B = 100)
#> J_min = 0.520 (SD 0.241) [borderline]
#> 95% bootstrap percentile interval: [0.206, 0.843]
#> Cluster sizes: 132, 81, 87

Compare against the conventional Ward-Euclidean default:

we <- boot_jaccard(Z, distance = "euclidean", linkage = "ward.D2", k = 3, B = 100, seed = 2024)
we
#> Configuration: euclidean distance, ward.D2 linkage, K = 3 (B = 100)
#> J_min = 0.498 (SD 0.216) [unstable]
#> 95% bootstrap percentile interval: [0.219, 0.833]
#> Cluster sizes: 121, 77, 102

Real-data example: the colon dataset

data(colon_survival)
Zc <- embed_survival(
  time  = colon_survival[, c("T_recur", "T_death")],
  event = colon_survival[, c("E_recur", "E_death")]
)
ca_colon <- boot_jaccard(Zc, "cosine", "average", k = 3, B = 100, seed = 2024)
we_colon <- boot_jaccard(Zc, "euclidean", "ward.D2", k = 3, B = 100, seed = 2024)
data.frame(
  method = c("cosine-average", "Ward-Euclidean"),
  J_min = c(ca_colon$J_min, we_colon$J_min)
)
#>           method     J_min
#> 1 cosine-average 0.6035493
#> 2 Ward-Euclidean 0.7320246

As in the manuscript’s real-data application, the cosine-average advantage seen in simulation does not universally transfer: Ward-Euclidean is competitive (often stronger) on this dataset, motivating per-dataset empirical selection via bootstrap Jaccard stability rather than a fixed default.

The chaining diagnostic

diag_single  <- chaining_diagnostic(Z, "cosine", "single",  k = 3, B = 100, seed = 2024)
diag_average <- chaining_diagnostic(Z, "cosine", "average", k = 3, B = 100, seed = 2024)
data.frame(
  linkage  = c("single", "average"),
  ARI      = c(diag_single$ARI, diag_average$ARI),
  J_min    = c(diag_single$J_min, diag_average$J_min),
  delta_CA = c(diag_single$delta_CA, diag_average$delta_CA),
  flagged  = c(diag_single$flagged, diag_average$flagged)
)
#>   linkage       ARI     J_min     delta_CA flagged
#> 1  single 0.2050489 0.1142393  0.090809627   FALSE
#> 2 average 0.5151426 0.5198932 -0.004750603   FALSE

Monte Carlo replication

mc <- mc_replicate(M = 200, n = 518, B = 200)
mc
plot(mc)