about summary refs log tree commit diff
path: root/src/routes/plot.rs
diff options
context:
space:
mode:
authorPjotr Prins <pjotr.public01@thebird.nl>2026-11-16 17:17:11 +0000
committerPjotr Prins <pjotr.public01@thebird.nl>2026-11-16 17:17:11 +0000
commitea3dd926211e8db4a0d7d3739a606440b888e8b0 (patch)
tree31b58cd0126960e70a76e45dc2c3b7c9a1c6d0b6 /src/routes/plot.rs
parent33e837e771e07936c808fb3aeb3540525691718c (diff)
downloadgenenetwork4-main.tar.gz
correlation matrix: clustered heatmap and its plot HEAD main
`"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/plot.rs')
-rw-r--r--src/routes/plot.rs97
1 files changed, 97 insertions, 0 deletions
diff --git a/src/routes/plot.rs b/src/routes/plot.rs
index fd56abc..2b4c043 100644
--- a/src/routes/plot.rs
+++ b/src/routes/plot.rs
@@ -817,6 +817,103 @@ pub async fn plot_pca(
     Ok(svg_response(rendered))
 }
 
+
+#[utoipa::path(post, path = "/plot/heatmap",
+    summary = "Draw the clustered heatmap of a correlation matrix, as an SVG",
+    description = "Post the response of POST /compute/correlation/matrix back (as-is) after \
+asking it for `\"cluster\": true`, and get the figure scripts/plot-heatmap.py draws: the r \
+matrix in the average-linkage order, one dendrogram showing why those traits are neighbours, \
+and a diverging colour scale with blue negative and red positive. Nothing is recomputed — the \
+order comes from the reply. image/svg+xml, not the JSON envelope; `x-plot-summary` carries the \
+plotter's one-line summary.",
+    params(PlotParams),
+    request_body = serde_json::Value,
+    responses(
+        (status = 200, description = "The SVG", body = String, content_type = "image/svg+xml"),
+        Unauthorized,
+        (status = 422, description = "The posted body carries no clustered order", body = ApiError),
+        (status = 502, description = "The plotter failed", body = ApiError)
+    )
+)]
+#[gnauth(token_only)]
+pub async fn plot_heatmap(
+    ctx: Ctx,
+    _token: AuthToken,
+    Query(plot_params): Query<PlotParams>,
+    Json(posted): Json<serde_json::Value>,
+) -> Result<Response, ApiError> {
+    let rid = ctx.request_info();
+    if let Err(detail) = check_heatmap_result(&posted) {
+        return Err(ApiError::new(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "not_a_heatmap_result",
+            "Not a clustered matrix",
+            detail,
+            "plot_heatmap",
+        )
+        .with_request_id(rid));
+    }
+    let config = Config::load();
+    let mut extra: Vec<String> = Vec::new();
+    if let Some(title) = plot_params.title.as_deref() {
+        extra.push("--title".to_string());
+        extra.push(title.to_string());
+    }
+    let borrowed: Vec<&str> = extra.iter().map(String::as_str).collect();
+    let rendered = plot::render(
+        &config.plot_python,
+        &config.heatmap_plotter,
+        std::path::Path::new(&config.gemma_cache_dir),
+        &posted,
+        plot_params
+            .trait_label
+            .as_deref()
+            .or(plot_params.title.as_deref())
+            .unwrap_or(""),
+        &borrowed,
+    )
+    .await
+    .map_err(|error| {
+        ApiError::new(
+            StatusCode::BAD_GATEWAY,
+            "plot_failed",
+            "The plotter failed",
+            error.to_string(),
+            "plot_heatmap",
+        )
+        .with_request_id(rid)
+    })?;
+    Ok(svg_response(rendered))
+}
+
+/// The posted body must carry `heatmap.order` from the matrix endpoint.
+fn check_heatmap_result(result: &serde_json::Value) -> Result<(), String> {
+    let data = result.get("data").unwrap_or(result);
+    let heatmap = data
+        .get("heatmap")
+        .ok_or("the posted body has no `heatmap` object: ask /compute/correlation/matrix for \
+                \"cluster\": true first")?;
+    let order = heatmap
+        .get("order")
+        .and_then(|order| order.as_array())
+        .ok_or("`heatmap.order` is missing")?;
+    if order.len() < 2 {
+        return Err("a heatmap needs at least two traits".to_string());
+    }
+    let traits = data
+        .get("traits")
+        .and_then(|traits| traits.as_array())
+        .ok_or("the posted body has no `traits` array")?;
+    if traits.len() != order.len() {
+        return Err(format!(
+            "`heatmap.order` lists {} trait(s) but `traits` has {}",
+            order.len(),
+            traits.len()
+        ));
+    }
+    Ok(())
+}
+
 /// The posted body must carry `pca.components`, from the matrix endpoint.
 fn check_pca_result(result: &serde_json::Value) -> Result<(), String> {
     let pca = result