diff options
Diffstat (limited to 'src/routes')
| -rw-r--r-- | src/routes/correlation_matrix.rs | 29 | ||||
| -rw-r--r-- | src/routes/plot.rs | 97 |
2 files changed, 126 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 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 |
