diff options
| author | Pjotr Prins <pjotr.public01@thebird.nl> | 2026-11-16 17:17:11 +0000 |
|---|---|---|
| committer | Pjotr Prins <pjotr.public01@thebird.nl> | 2026-11-16 17:17:11 +0000 |
| commit | ea3dd926211e8db4a0d7d3739a606440b888e8b0 (patch) | |
| tree | 31b58cd0126960e70a76e45dc2c3b7c9a1c6d0b6 /src/routes/correlation_matrix.rs | |
| parent | 33e837e771e07936c808fb3aeb3540525691718c (diff) | |
| download | genenetwork4-main.tar.gz | |
`"cluster": true` adds `heatmap: {order, merges, max_height}` to the matrix
reply and `POST /plot/heatmap` draws it: the r matrix in that order, the
dendrogram that produced it, and a diverging scale with blue negative and red
positive. A reader can see *why* two traits are neighbours instead of trusting
an ordering.
Clustering decisions, all recorded because an unrepeatable clustering is worse
than none:
* distance `1 - r` -- the usual choice for correlations, and it keeps
anti-correlated traits apart, which is what a heatmap of correlations should
show;
* **average linkage (UPGMA)** -- single linkage chains along a gradient and
complete linkage makes one flat blob out of noisy traits; average is the
compromise GN1's R heatmaps used too;
* **deterministic ties and leaf order** (lower index first), so two runs on one
matrix produce the same picture and plots stay diffable;
* a matrix with a **gap is refused** rather than clustered: an unknown distance
treated as 1 would invent a structure, and the reply's note says to drop
those traits and ask again.
Pairing with the PCA work this is the visual half of a collection: scree plot
for how much structure there is, clustered heatmap for where it is.
Monitor, as asked: `compute-correlation-heatmap` (order must be a permutation
with n-1 merges), `plot-heatmap`, and the plot endpoints that had no check at
all -- `plot-gemma` and `plot-bnw`, each posting a real compute result back.
Plots tier is now five checks, all ok; full run 47 ok, 0 failed, 1 skipped.
Diffstat (limited to 'src/routes/correlation_matrix.rs')
| -rw-r--r-- | src/routes/correlation_matrix.rs | 29 |
1 files changed, 29 insertions, 0 deletions
diff --git a/src/routes/correlation_matrix.rs b/src/routes/correlation_matrix.rs index 2e6c883..9a433b6 100644 --- a/src/routes/correlation_matrix.rs +++ b/src/routes/correlation_matrix.rs @@ -65,6 +65,11 @@ pub struct MatrixRequest { /// Fewest paired observations a cell may have. Defaults to 6. #[serde(default)] pub min_overlap: Option<usize>, + /// Also return a clustered ordering (and its tree) for a heatmap: average + /// linkage on `1 - r`. The matrix is symmetric, so one order serves both + /// axes. + #[serde(default)] + pub cluster: Option<bool>, /// Also return a PCA of the matrix (eigenvalues, explained variance, /// loadings over the traits whose every cell is valid). Off by default: /// the r matrix is worth reading on its own first. @@ -201,6 +206,16 @@ pub async fn correlation_matrix( if let Some(pca) = &pca { body["pca"] = serde_json::to_value(pca).unwrap_or(serde_json::Value::Null); } + let clustering = if wanted.cluster.unwrap_or(false) { + // Refused rather than guessed when a cell is missing: an unknown + // distance treated as 1 would invent a structure and a plot of it. + crate::heatmap::cluster(&matrix.r, crate::pca::MAX_PCA_TRAITS) + } else { + None + }; + if let Some(clustering) = &clustering { + body["heatmap"] = serde_json::to_value(clustering).unwrap_or(serde_json::Value::Null); + } Ok(Json( ctx.envelope(body) .with_note(&format!( @@ -227,6 +242,19 @@ pub async fn correlation_matrix( "Cells with fewer than min_overlap observations are null in r and p, and their \ n still says how many there were.", ) + .with_note(&match (&clustering, wanted.cluster.unwrap_or(false)) { + (Some(clustering), _) => format!( + "Clustering: average linkage on 1 - r, {} merge(s), largest distance {:.3}; \ + `heatmap.order` is the drawing order for both axes.", + clustering.merges.len(), + clustering.max_height + ), + (None, true) => "No clustering: the matrix has a gap (a null cell), so some \ + distances are unknown -- drop those traits and ask again." + .to_string(), + (None, false) => "No clustering: pass \"cluster\": true for a heatmap order." + .to_string(), + }) .with_note(&match &pca { Some(pca) if pca.components.is_empty() => format!( "PCA: not computed -- {} trait(s) were usable and it needs at least 2, and \ @@ -448,6 +476,7 @@ mod tests { method: None, corr_samples_group: None, min_overlap: None, + cluster: None, pca: None, }; // build() would go to the database; the arithmetic is what is tested |
