--- title: "Introduction to survPhenoStab" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Introduction to survPhenoStab} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>") ``` ```{r setup} library(survPhenoStab) ``` ## 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: - `embed_survival()`: build a standardised, mixed continuous-binary feature-space embedding from multiple time-to-event endpoints. - `sim_competing_risks()`: the paper's competing-risks data-generating mechanism, for simulation studies. - `cluster_configs()` / `cluster_assign()`: enumerate and fit the distance-linkage-K grid. - `boot_jaccard()`: bootstrap Jaccard cluster-stability assessment. - `chaining_diagnostic()`: the Delta_CA chaining-artefact diagnostic. - `select_k()`: cluster-number selection combining silhouette, gap statistic and bootstrap stability. - `benchmark_methods()`: comparison against k-means and Gaussian mixtures. - `mc_replicate()`: Monte Carlo replication of the stability comparison across simulated datasets. ## A minimal simulated example ```{r} sim <- sim_competing_risks(n = 300, seed = 2024) Z <- sim$embedding dim(Z) ``` Fit and assess one configuration: ```{r} ca <- boot_jaccard(Z, distance = "cosine", linkage = "average", k = 3, B = 100, seed = 2024) ca ``` Compare against the conventional Ward-Euclidean default: ```{r} we <- boot_jaccard(Z, distance = "euclidean", linkage = "ward.D2", k = 3, B = 100, seed = 2024) we ``` ## Real-data example: the colon dataset ```{r} 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) ) ``` 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 ```{r} 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) ) ``` ## Monte Carlo replication ```{r, eval = FALSE} mc <- mc_replicate(M = 200, n = 518, B = 200) mc plot(mc) ```