| Title: | Stability-Driven Hierarchical Clustering for Multi-Endpoint Survival Phenotyping |
|---|---|
| Description: | 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" (submitted to Computers in Biology and Medicine). Provides survival feature-space embedding for multiple time-to-event endpoints, a competing-risks data-generating mechanism for simulation, an exhaustive sweep over valid distance-linkage-K configurations, bootstrap Jaccard cluster-stability assessment, a chaining- artefact diagnostic (Delta_CA), cluster-number selection combining silhouette width, the gap statistic and bootstrap stability, and benchmarking against k-means and Gaussian mixture models. |
| Authors: | Oindrila Roy Chowdhury [aut, cre], Bapan Kalita [aut], Dilip Chandra Nath [aut], Atanu Bhattacharjee [aut] |
| Maintainer: | Oindrila Roy Chowdhury <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-11-18 00:15:07 UTC |
| Source: | https://github.com/cran/survPhenoStab |
Table 6 in the manuscript reports these numbers but there was no code for k-means/GMM anywhere in the original scripts, so this rebuilds the comparison from scratch: the chosen hierarchical configuration against k-means, a Gaussian mixture (EM, full covariance), and Ward-Euclidean, all on the same embedding at the same K. Same three metrics as elsewhere in the package (J_min, ARI, silhouette) so the rows are directly comparable, plus wall-clock time since the manuscript reports that too (k-means/GMM are noticeably slower to bootstrap than hierarchical clustering, since each resample refits the whole model).
benchmark_methods( Z, k, proposed_distance = "cosine", proposed_linkage = "average", include_ward = TRUE, B = 200, kmeans_nstart_ref = 20, kmeans_nstart_boot = 3, seed = 42 )benchmark_methods( Z, k, proposed_distance = "cosine", proposed_linkage = "average", include_ward = TRUE, B = 200, kmeans_nstart_ref = 20, kmeans_nstart_boot = 3, seed = 42 )
Z |
numeric embedding matrix. |
k |
number of clusters. |
proposed_distance, proposed_linkage
|
the configuration treated as
"proposed" (default |
include_ward |
logical; also benchmark Ward-Euclidean as an
explicit baseline row (default |
B |
bootstrap resamples for |
kmeans_nstart_ref, kmeans_nstart_boot
|
number of random k-means initialisations on the reference fit and on each bootstrap fit, respectively (defaults 20 and 3, matching the manuscript's stated computational protocol in Section 5). |
seed |
random seed. |
a data.frame with one row per method and columns
method, J_min, ARI, silhouette, time_s.
Ports jmin_for_config() / jmin_real(): assesses the
stability of a hierarchical clustering configuration via bootstrap
resampling (manuscript Section 2.5.2, Eq. 4). For each of B
bootstrap resamples, the data are re-clustered under the same
configuration and the per-cluster Jaccard coefficient against the
reference partition is recorded; J_min is the minimum, over
clusters, of the mean Jaccard across resamples.
boot_jaccard( Z, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k, B = 500, seed = 42 )boot_jaccard( Z, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k, B = 500, seed = 42 )
Z |
numeric embedding matrix (observations in rows). |
distance, linkage, k
|
as in |
B |
number of bootstrap resamples (default 500, the manuscript's primary-replicate value; the manuscript also uses B = 200 for the Monte Carlo replication and real-data analyses). |
seed |
random seed for the bootstrap resampling. |
a list of class "spstab_config" with elements:
partition |
the reference-partition cluster labels |
J_min |
minimum mean per-cluster Jaccard |
J_min_sd |
bootstrap SD of the Jaccard for the limiting cluster |
J_per_cluster |
mean Jaccard for every cluster |
sizes |
reference cluster sizes |
stability_class |
|
ci |
a length-2 vector, the 2.5 interval of the per-resample minimum-cluster Jaccard. |
set.seed(1) Z <- matrix(rnorm(200), 100, 2) res <- boot_jaccard(Z, distance = "euclidean", linkage = "ward.D2", k = 3, B = 50) res$J_minset.seed(1) Z <- matrix(rnorm(200), 100, 2) res <- boot_jaccard(Z, distance = "euclidean", linkage = "ward.D2", k = 3, B = 50) res$J_min
This one had no code behind it anywhere in the original analysis – the manuscript reports Delta_CA values in Table 2 but the formula was never actually implemented. Wrote it here directly from the definition.
chaining_diagnostic( Z, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k, B = 200, seed = 42, threshold = 0.2 )chaining_diagnostic( Z, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k, B = 200, seed = 42, threshold = 0.2 )
Z |
numeric embedding matrix. |
distance, linkage, k
|
as in |
B |
bootstrap resamples (used for both J_min and ARI – see Details below on why they share the same resamples). |
seed |
random seed. |
threshold |
Delta_CA cutoff for flagging, default 0.20 (manuscript's value). |
The idea: single linkage tends to produce one big "everything" cluster plus a few near-singleton leftovers. Resample the data and re-cluster – the big cluster comes back looking almost identical every time (ARI stays high), but the tiny leftover clusters get reshuffled at random (J_min drops). ARI and J_min normally track each other; when they pull apart like this, that gap IS the chaining signature. Delta_CA just measures the gap directly instead of eyeballing two separate numbers.
Threshold of 0.20 is the manuscript's own cutoff – empirically chosen there, not derived from anything, so treat it as a rule of thumb rather than a hard boundary.
list with ARI, J_min, delta_CA, flagged,
and stability (the full boot_jaccard output, in
case you want the per-cluster breakdown too).
Applies agglomerative hierarchical clustering under a given distance
metric and linkage criterion and cuts the dendrogram at K
clusters. Ward's criterion is restricted to Euclidean distance, matching
the manuscript's stated restriction (Section 2.4) that Ward.D2 is not
combined with non-Euclidean metrics.
cluster_assign( Z, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k )cluster_assign( Z, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k )
Z |
numeric embedding matrix, observations in rows (typically the
output of |
distance |
one of |
linkage |
one of |
k |
number of clusters to cut the dendrogram into. |
an integer vector of cluster labels, length nrow(Z).
Reproduces the 27-configuration grid of the manuscript (Section 2.4,
Figure 1): 3 distance metrics x 3 linkage criteria (Ward.D2, complete,
average), with Ward.D2 restricted to Euclidean distance (9 valid
distance-linkage pairs), each evaluated at every value of k
(default 3:5), for 27 candidate configurations by default.
Single linkage is deliberately excluded from the default grid, matching
the manuscript's definition of the primary 27-configuration sweep
(Section 2.4); pass linkages including "single" explicitly
to reproduce the separate single-linkage chaining-artefact exploration
of Table 2.
cluster_configs( distances = c("cosine", "euclidean", "manhattan"), linkages = c("average", "complete", "ward.D2"), k = 3:5 )cluster_configs( distances = c("cosine", "euclidean", "manhattan"), linkages = c("average", "complete", "ward.D2"), k = 3:5 )
distances |
character vector of distance metrics to include. |
linkages |
character vector of linkage criteria to include.
Default |
k |
integer vector of cluster counts to evaluate (default
|
a data.frame with columns distance, linkage, k,
one row per valid configuration.
The public colon cancer dataset (Moertel et al. 1990), reshaped from the
long form in the survival package (survival::colon) into
one row per patient with both time-to-event endpoints as columns, ready
for embed_survival. Used for the real-data application in
the manuscript, Section 4.1.
colon_survivalcolon_survival
A data.frame with 929 rows and 5 columns:
patient identifier
time to recurrence or censoring, in days
recurrence event indicator (1 = recurrence, 0 = censored)
time to death or censoring, in days
death event indicator (1 = death, 0 = censored)
survival::colon; Moertel CG, Fleming TR, MacDonald JS, et
al. (1990) "Levamisole and fluorouracil for adjuvant therapy of
resected colon carcinoma." New England Journal of Medicine
322:352-358.
data(colon_survival) Z <- embed_survival( time = colon_survival[, c("T_recur", "T_death")], event = colon_survival[, c("E_recur", "E_death")] ) dim(Z)data(colon_survival) Z <- embed_survival( time = colon_survival[, c("T_recur", "T_death")], event = colon_survival[, c("E_recur", "E_death")] ) dim(Z)
Computes pairwise cosine distance (1 - cosine similarity) on a numeric
matrix, guarding against zero-norm rows exactly as described in the
manuscript (Section 2.3): row norms below tol are floored to
tol before normalisation, and a warning is issued (matching the
code's automatic near-zero-norm check).
cosine_dist(Z, tol = 1e-08)cosine_dist(Z, tol = 1e-08)
Z |
a numeric matrix, observations in rows. |
tol |
minimum row norm; rows with |
an object of class "dist" (as produced by
as.dist), suitable for stats::hclust().
Constructs the standardised, mixed continuous-binary feature-space embedding used throughout the stability-driven clustering framework (manuscript Section 2.2, Eq. 2): each time-to-event endpoint contributes a log-transformed event time and a binary event indicator, and the full matrix is centred and scaled to zero mean / unit variance per column.
embed_survival(time, event, log_floor = 0.001, standardize = TRUE)embed_survival(time, event, log_floor = 0.001, standardize = TRUE)
time |
a numeric matrix or data.frame of observed times, one column
per endpoint (e.g. columns |
event |
a numeric/integer matrix or data.frame of event indicators
(1 = event, 0 = censored), same dimensions and column order as
|
log_floor |
small positive constant used in |
standardize |
logical; if |
When standardize = TRUE, a column with zero variance
(for example the event indicator of an endpoint with no censoring,
where every patient has the event) carries no information for
clustering. Such columns are centred to zero rather than divided by a
zero standard deviation, so the embedding contains no NaN
values, and a warning names the affected columns.
Zero-norm rows (all-zero after standardisation) are not
possible after centring in general, but if cosine_dist is used
downstream on an embedding where every observation is identical in a
subset of columns, near-zero-norm rows can occur; cosine_dist
guards against this exactly as in the manuscript (Section 2.3).
A numeric matrix with 2 * ncol(time) columns, ordered
log T_1, E_1, log T_2, E_2, ..., with column names
logT_<endpoint> / E_<endpoint> taken from
colnames(time). A leading T_ prefix on the time column
names (e.g. T_recur) is dropped, giving logT_recur /
E_recur rather than logT_T_recur / E_T_recur.
set.seed(1) time_mat <- cbind(OS = rexp(50, 0.05), PFS = rexp(50, 0.08)) event_mat <- cbind(OS = rbinom(50, 1, 0.7), PFS = rbinom(50, 1, 0.8)) Z <- embed_survival(time_mat, event_mat) dim(Z)set.seed(1) time_mat <- cbind(OS = rexp(50, 0.05), PFS = rexp(50, 0.08)) event_mat <- cbind(OS = rbinom(50, 1, 0.7), PFS = rbinom(50, 1, 0.8)) Z <- embed_survival(time_mat, event_mat) dim(Z)
Runs the stability-driven clustering pipeline on an embedding and knits a single self-contained HTML report covering: the bootstrap stability result for the chosen configuration, the stability heatmap across all valid configurations, the chaining diagnostic, a silhouette plot, a dendrogram, and (if supplied) a covariate heatmap and Kaplan-Meier curves by cluster. Intended as a quick, shareable summary of one analysis run, e.g. to attach to a manuscript revision or share with co-authors.
generate_report( Z, time = NULL, event = NULL, covariates = NULL, covariate_names = NULL, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k = 3, B = 200, compare_ward = TRUE, seed = 42, title = "survPhenoStab analysis report", output_file = "survPhenoStab_report.html", output_dir = getwd(), open = interactive() )generate_report( Z, time = NULL, event = NULL, covariates = NULL, covariate_names = NULL, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k = 3, B = 200, compare_ward = TRUE, seed = 42, title = "survPhenoStab analysis report", output_file = "survPhenoStab_report.html", output_dir = getwd(), open = interactive() )
Z |
numeric embedding matrix (typically from
|
time, event
|
optional numeric matrices of times/event indicators
(one column per endpoint) to include Kaplan-Meier curves by cluster;
both must be supplied together, or both left |
covariates |
optional numeric matrix of covariates (one row per
observation, aligned with |
covariate_names |
optional display names for |
distance, linkage, k
|
the configuration to report on in detail
(default |
B |
bootstrap resamples for the headline stability result (the
stability heatmap and chaining diagnostic use
|
compare_ward |
logical; also report the Ward-Euclidean J_min for
comparison (default |
seed |
random seed. |
title |
report title. |
output_file |
file name for the rendered report (default
|
output_dir |
directory to write the report into (default the current working directory). |
open |
logical; if |
invisibly, the full path to the rendered HTML file.
sim <- sim_competing_risks(n = 200, seed = 1) generate_report(sim$embedding, time = sim$time, event = sim$event, covariates = sim$covariates, B = 50, output_dir = tempdir(), open = FALSE)sim <- sim_competing_risks(n = 200, seed = 1) generate_report(sim$embedding, time = sim$time, event = sim$event, covariates = sim$covariates, B = 50, output_dir = tempdir(), open = FALSE)
Direct port of logrank_chisq(): computes the multi-sample
log-rank chi-squared statistic (observed-minus-expected events, with
the standard log-rank variance-covariance matrix) for testing
equality of survival across the groups defined by group
(e.g. recovered cluster labels). Used descriptively in the manuscript
(Section 3.3 / 4.1) to characterise separation between recovered
phenotypes; as noted there, because cluster assignment and this test
use the same data, the resulting p-value is descriptive only and does
not carry standard inferential interpretation.
logrank_test(time, event, group)logrank_test(time, event, group)
time |
numeric vector of observed times. |
event |
integer/logical vector of event indicators (1/TRUE = event). |
group |
vector (numeric, character or factor) of group labels,
same length as |
a list with chisq, df, and p_value.
Ports one_replicate() plus the driving loop from
run_mc_python.py: repeats data generation, embedding, clustering
and bootstrap-stability validation across M independent
simulation replicates (manuscript Section 2.6), recording the
per-replicate difference (Eq. 6) and testing
whether it is consistently positive via a paired one-sided Wilcoxon
signed-rank test.
mc_replicate( M = 200, n = 518, B = 200, base_seed = 1000, sim_args = list(), progress = TRUE )mc_replicate( M = 200, n = 518, B = 200, base_seed = 1000, sim_args = list(), progress = TRUE )
M |
number of Monte Carlo replicates (default 200, matching the manuscript). |
n |
patients per replicate (default 518). |
B |
bootstrap resamples per replicate per configuration (default 200, matching the manuscript's Monte Carlo protocol; the manuscript uses B = 500 only for the single primary-replicate analysis). |
base_seed |
base random seed; replicate |
sim_args |
a list of additional arguments passed to
|
progress |
logical; print progress every 10 replicates. |
an object of class "spstab_mc": a list with
cos_avg, ward, delta (numeric vectors, length M),
wilcoxon (the htest object, one-sided "greater"), and
summary (a one-row data.frame of means, SDs, percent positive).
mc <- mc_replicate(M = 20, n = 100, B = 50) mcmc <- mc_replicate(M = 20, n = 100, B = 50) mc
Reproduces the manuscript's Figure 4: for each cluster, shows the within-cluster mean of each (standardised) covariate as a coloured grid cell, so that clusters can be characterised by which covariates are above/below the overall cohort average.
plot_covariate_heatmap( covariates, labels, covariate_names = NULL, standardize = TRUE, order_by = NULL, main = "Standardised covariate profiles across clusters" )plot_covariate_heatmap( covariates, labels, covariate_names = NULL, standardize = TRUE, order_by = NULL, main = "Standardised covariate profiles across clusters" )
covariates |
a numeric matrix or data.frame of covariates, one row
per patient, one column per covariate (e.g. the |
labels |
integer/factor vector of cluster labels, length
|
covariate_names |
optional character vector of display names for
the covariate columns (default: |
standardize |
logical; if |
order_by |
optionally, a covariate name (or column index) to sort
the displayed cluster rows by (descending), so e.g. the highest-risk
cluster appears first. Default |
main |
plot title. |
invisibly, the cluster x covariate matrix of means that was plotted (so you can inspect the exact numbers behind the colours).
sim <- sim_competing_risks(n = 200, seed = 1) labels <- cluster_assign(sim$embedding, "cosine", "average", k = 3) plot_covariate_heatmap(sim$covariates, labels, covariate_names = c("Functional status", "Disease severity", "Comorbidity index", "Age", "Biomarker level"))sim <- sim_competing_risks(n = 200, seed = 1) labels <- cluster_assign(sim$embedding, "cosine", "average", k = 3) plot_covariate_heatmap(sim$covariates, labels, covariate_names = c("Functional status", "Disease severity", "Comorbidity index", "Age", "Biomarker level"))
Plots the merge tree for a given distance-linkage configuration and
outlines the k-cluster cut with coloured boxes, using
stats::hclust / stats::rect.hclust under the hood. Useful
for seeing *how* patients get merged step by step, which a cluster-label
vector alone doesn't show.
plot_dendrogram( Z, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k = 3, labels = NULL, main = NULL, box_border = c("#B2182B", "#2166AC", "#1B7837", "#B15928", "#762A83") )plot_dendrogram( Z, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k = 3, labels = NULL, main = NULL, box_border = c("#B2182B", "#2166AC", "#1B7837", "#B15928", "#762A83") )
Z |
numeric embedding matrix (observations in rows). |
distance, linkage
|
as in |
k |
number of clusters to outline with boxes (set to |
labels |
optional vector of leaf labels (e.g. patient IDs); default suppresses leaf labels, which is usually more readable for n > ~50. |
main |
plot title. |
box_border |
colours used for the |
invisibly, the underlying hclust object.
sim <- sim_competing_risks(n = 80, seed = 1) plot_dendrogram(sim$embedding, "cosine", "average", k = 3)sim <- sim_competing_risks(n = 80, seed = 1) plot_dendrogram(sim$embedding, "cosine", "average", k = 3)
Reproduces the manuscript's Figure 3: for one or more time-to-event
endpoints, plots Kaplan-Meier curves split by cluster label, with the
descriptive log-rank chi-squared (via logrank_test)
annotated on each panel. As in the manuscript, these log-rank
statistics are descriptive only, since the same data were used to form
the clusters and to test them.
plot_km_by_cluster(time, event, labels, endpoint_names = NULL, mfrow = NULL)plot_km_by_cluster(time, event, labels, endpoint_names = NULL, mfrow = NULL)
time |
a numeric matrix/data.frame of times, one column per
endpoint (e.g. the |
event |
a numeric/integer matrix/data.frame of event indicators,
same shape as |
labels |
cluster labels, length |
endpoint_names |
optional display names for the endpoints
(default: |
mfrow |
optional |
invisibly, a list of logrank_test results, one
per endpoint.
sim <- sim_competing_risks(n = 200, seed = 1) labels <- cluster_assign(sim$embedding, "cosine", "average", k = 3) plot_km_by_cluster(sim$time, sim$event, labels)sim <- sim_competing_risks(n = 200, seed = 1) labels <- cluster_assign(sim$embedding, "cosine", "average", k = 3) plot_km_by_cluster(sim$time, sim$event, labels)
The standard silhouette diagnostic plot (Rousseeuw 1987): one horizontal
bar per patient, grouped by cluster and sorted from best- to
worst-clustered within each group, so you can see which *individual*
patients are ambiguous or mis-clustered rather than only the cluster
average (as reported by silhouette_width).
plot_silhouette( Z, labels, distance = c("cosine", "euclidean", "manhattan"), main = NULL )plot_silhouette( Z, labels, distance = c("cosine", "euclidean", "manhattan"), main = NULL )
Z |
numeric embedding matrix (observations in rows). |
labels |
integer/factor vector of cluster labels. |
distance |
one of |
main |
plot title. |
invisibly, a data.frame with columns label, sil
(silhouette value) and order (plotting order), one row per
observation.
sim <- sim_competing_risks(n = 150, seed = 1) labs <- cluster_assign(sim$embedding, "cosine", "average", k = 3) plot_silhouette(sim$embedding, labs, "cosine")sim <- sim_competing_risks(n = 150, seed = 1) labs <- cluster_assign(sim$embedding, "cosine", "average", k = 3) plot_silhouette(sim$embedding, labs, "cosine")
New visualisation (not in the manuscript): computes J_min via
boot_jaccard for every valid distance-linkage combination
(see cluster_configs) at a fixed k, and displays
the result as a coloured grid. This makes the manuscript's central
argument – "check stability empirically rather than assuming a
default" – visible at a glance, instead of requiring a table lookup.
plot_stability_heatmap( Z, k, distances = c("cosine", "euclidean", "manhattan"), linkages = c("average", "complete", "ward.D2"), B = 100, seed = 42, main = sprintf("Bootstrap stability (J_min) at K = %d", k) )plot_stability_heatmap( Z, k, distances = c("cosine", "euclidean", "manhattan"), linkages = c("average", "complete", "ward.D2"), B = 100, seed = 42, main = sprintf("Bootstrap stability (J_min) at K = %d", k) )
Z |
numeric embedding matrix. |
k |
number of clusters to evaluate at. |
distances, linkages
|
passed to |
B |
bootstrap resamples per configuration (kept modest by default
since this function fits |
seed |
random seed. |
main |
plot title. |
invisibly, a distance x linkage matrix of J_min values (NA where a combination is invalid, e.g. Ward.D2 with a non-Euclidean distance).
sim <- sim_competing_risks(n = 150, seed = 1) plot_stability_heatmap(sim$embedding, k = 3, B = 30)sim <- sim_competing_risks(n = 150, seed = 1) plot_stability_heatmap(sim$embedding, k = 3, B = 30)
Another one with no existing code – Section 2.5.5 describes the procedure in prose (three criteria, majority vote) but nothing in the original scripts actually ran it.
select_k( Z, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k_range = 2:6, B = 200, gap_B = 100, min_frac = 0.05, seed = 42 )select_k( Z, distance = c("cosine", "euclidean", "manhattan"), linkage = c("average", "complete", "ward.D2", "single"), k_range = 2:6, B = 200, gap_B = 100, min_frac = 0.05, seed = 42 )
Z |
numeric embedding matrix. |
distance, linkage
|
as in |
k_range |
integer vector of candidate K values (default 2:6, matching the manuscript's Section 3.2 sweep). |
B |
number of bootstrap resamples for the stability curve
(passed to |
gap_B |
number of Monte Carlo replicates used by
|
min_frac |
minimum cluster size as a fraction of n (default 0.05). |
seed |
random seed. |
Why three criteria instead of one: silhouette width and the gap statistic are both "separation" measures – they ask whether the clusters look distinct from each other on a single fixed dataset. They say nothing about whether the same clusters would show up again if you had collected a slightly different sample. That's what the bootstrap J_min curve adds. A K that only wins on separation but not stability is probably overfitting to this one sample, so requiring 2-out-of-3 agreement is a guard against that rather than just an arbitrary voting rule.
The minimum-cluster-size rule exists because of a real failure mode you can hit with bootstrap stability alone: pushing K higher and higher eventually peels off tiny 1-2 patient clusters that look artificially "stable" in the bootstrap (small clusters can spuriously resample well just because there's so little of them to get wrong). Excluding any K whose smallest cluster is under 5 stops that from winning the vote.
Worth knowing: this can return k_selected = NA if none of the
three criteria agree. That's not a bug – it's the function honestly
reporting "there's no clean consensus here," which does happen on real
(messy) data. See votes to see how close it was.
a list with elements:
silhouette |
named numeric vector, average silhouette width per K |
gap |
the |
k_silhouette |
K selected by maximum silhouette width |
k_gap |
K selected by the gap statistic's one-SE rule |
J_min_curve |
named numeric vector, bootstrap J_min per K, after excluding K values that violate the minimum cluster size constraint |
k_stability |
K maximising the (constrained) stability curve |
k_selected |
final K, i.e. the value in |
votes |
table of how many of the three criteria selected each K |
Computes the silhouette value (manuscript Section 2.5.1, Eq. 3) for
every observation individually, directly on the distance matrix implied
by distance. silhouette_width is a thin wrapper
that averages this vector; use this function directly when you need
per-patient values, e.g. for plot_silhouette.
silhouette_values(Z, labels, distance = c("cosine", "euclidean", "manhattan"))silhouette_values(Z, labels, distance = c("cosine", "euclidean", "manhattan"))
Z |
numeric embedding matrix (observations in rows). |
labels |
integer vector of cluster labels, length |
distance |
one of |
a numeric vector of length nrow(Z), one silhouette value
per observation, in the same order as labels.
Ports silhouette_score(): the mean of silhouette_values
(manuscript Section 2.5.1, Eq. 3). As noted in the manuscript, silhouette
values are only comparable *within* a distance metric family, not across
metrics.
silhouette_width(Z, labels, distance = c("cosine", "euclidean", "manhattan"))silhouette_width(Z, labels, distance = c("cosine", "euclidean", "manhattan"))
Z |
numeric embedding matrix (observations in rows). |
labels |
integer vector of cluster labels, length |
distance |
one of |
the average silhouette width (numeric scalar).
Ports the competing-risks data-generating mechanism used in the
manuscript (Section 2.1, Eq. 1): three correlated time-to-event
endpoints (OS, PFS, LRFS) are generated from Weibull cause-specific
hazards with correlated Gaussian covariates, administrative censoring
at tau, random exponential censoring, and the clinical
constraint T_PFS <= T_OS enforced by rejection sampling.
sim_competing_risks( n = 518, seed = 2024, rho = 0.3, tau = 60, eta = 0.015, params = list(OS = list(lam = 0.01, gam = 1.4, beta = c(0.45, 0.3, -0.2, 0.25, -0.15)), PFS = list(lam = 0.018, gam = 1.25, beta = c(0.35, 0.4, -0.25, 0.2, -0.1)), LRFS = list(lam = 0.012, gam = 1.3, beta = c(0.3, 0.2, -0.15, 0.35, -0.2))), max_reject_iter = 50 )sim_competing_risks( n = 518, seed = 2024, rho = 0.3, tau = 60, eta = 0.015, params = list(OS = list(lam = 0.01, gam = 1.4, beta = c(0.45, 0.3, -0.2, 0.25, -0.15)), PFS = list(lam = 0.018, gam = 1.25, beta = c(0.35, 0.4, -0.25, 0.2, -0.1)), LRFS = list(lam = 0.012, gam = 1.3, beta = c(0.3, 0.2, -0.15, 0.35, -0.2))), max_reject_iter = 50 )
n |
number of patients to simulate. Default 518 (primary simulation replicate in the manuscript). |
seed |
integer random seed for reproducibility. |
rho |
constant pairwise covariate correlation (default 0.3). |
tau |
administrative censoring time in months (default 60). |
eta |
rate of the random exponential censoring distribution
(default 0.015), calibrated for approximately 30
|
params |
a named list with one element per endpoint (default
|
max_reject_iter |
maximum rejection-sampling iterations used to enforce T_PFS <= T_OS before falling back to T_PFS <- T_OS for any remaining violations (default 50, matching the analysis code). |
The independence-assumption caveat in the manuscript (Section 2.3) applies here too: the three endpoints are not generated independently (they share covariates X and the T_PFS <= T_OS constraint), so downstream distance metrics that assume independent dimensions are applied under a violated assumption by construction.
A list with elements:
time |
n x n_endpoint matrix of observed times |
event |
n x n_endpoint matrix of event indicators |
covariates |
n x p matrix of the underlying Gaussian covariates |
embedding |
the standardised feature-space embedding, i.e.
|
sim <- sim_competing_risks(n = 100, seed = 2024) dim(sim$embedding)sim <- sim_competing_risks(n = 100, seed = 2024) dim(sim$embedding)