---
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)
```
