//! `POST /plot/rqtl` and `POST /plot/gemma` -- the Manhattan plot of a //! mapping, as an SVG. //! //! They take the **mapping's own response** -- the JSON a //! `/compute/rqtl` or `/compute/gemma` call returned, posted back as-is -- //! and hand it to the deployment's plotter (`scripts/plot-rqtl.py`, //! `scripts/plot-gemma.py`), which is what those scripts were written //! for: `src/plot.rs` does the running. Nothing is recomputed, so a plot //! costs one script run and can be redrawn from a result you kept. //! //! The reply is an SVG, not an envelope: an image is not JSON, and the two //! JSON-free responses (`/` and `/openapi.json`) are the precedent. The //! plotter's one-line summary of the peak goes back in an `x-plot-summary` //! header, so a caller that cannot see the picture still learns where the //! peak is. use axum::Json; use axum::extract::Query; use axum::http::{HeaderValue, StatusCode, header}; use axum::response::{IntoResponse, Response}; use gnauth_macros::gnauth; use crate::auth::AuthToken; use crate::config::Config; use crate::error::{ApiError, Unauthorized}; use crate::plot; use crate::response::Ctx; use serde::Deserialize; /// Options shared by both plot endpoints. #[derive(Deserialize, utoipa::IntoParams)] pub struct PlotParams { /// Label for the plot's title, e.g. the trait id. Defaults to "rqtl" /// or "gemma". #[serde(rename = "trait")] pub trait_label: Option, /// Override the plot's title text. pub title: Option, /// GEMMA only: `true` draws GEMMA's Bonferroni line. Off by default -- a /// reference line is an annotation on the plot, not part of the result, and /// the same is true of the thresholds passed in `thresholds`. pub bonferroni: Option, /// Reference lines on a GEMMA plot, in LOD / -log10 p units, comma /// separated: the thresholds another engine computed for the same values /// (`/compute/bulklmm` prints them in its `notes`). Drawn alongside /// GEMMA's own Bonferroni line and labelled, so the two are never confused. pub thresholds: Option, /// Labels for those lines, comma separated and in the same order, e.g. /// "bulklmm alpha 0.05". Anything missing defaults to "bulklmm threshold". pub threshold_labels: Option, /// BulkLMM only: also draw the loosest line the reply reports /// (alpha 0.10). The default is the genome-wide 0.05 and the stricter 0.01. pub all_thresholds: Option, /// BNW only: which figure, `network` (the learned structure, default) or /// `posterior` (every candidate edge as a cell in a matrix). The diagram /// shows what survived; the matrix says how close an edge was to the /// threshold, which the diagram cannot. pub kind: Option, } /// The reference lines a caller passed, validated: `(value, label)`. fn external_thresholds( thresholds: Option<&str>, labels: Option<&str>, rid: &crate::response::RequestInfo, ) -> Result, ApiError> { let Some(thresholds) = thresholds else { return Ok(Vec::new()) }; let values: Vec<&str> = thresholds.split(',').map(str::trim).filter(|v| !v.is_empty()).collect(); if values.is_empty() { return Ok(Vec::new()); } let labels: Vec<&str> = labels .map(|labels| labels.split(',').map(str::trim).collect()) .unwrap_or_default(); let mut lines = Vec::with_capacity(values.len()); for (index, value) in values.iter().enumerate() { let parsed = value.parse::().map_err(|_| { ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "invalid_threshold", "Invalid threshold", format!("'{value}' is not a number; `thresholds` takes LOD / -log10 p values"), "plot", ) .with_request_id(rid.clone()) })?; if !parsed.is_finite() || parsed <= 0.0 { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "invalid_threshold", "Invalid threshold", format!("{parsed}: a reference line has to be a positive number"), "plot", ) .with_request_id(rid.clone())); } let label = labels .get(index) .copied() .filter(|label| !label.is_empty()) .unwrap_or("bulklmm threshold") .to_string(); lines.push((parsed, label)); } Ok(lines) } /// The trait a posted compute response says it mapped: the `Trait: ...` /// note `/compute/rqtl` writes. It is what makes two plots of two traits /// distinguishable at a glance -- the *data* differs, but without this the /// title of every one of them said "trait rqtl". fn trait_from_document(posted: &serde_json::Value) -> Option { posted["notes"] .as_array()? .iter() .filter_map(|note| note.as_str()) .find_map(|note| note.strip_prefix("Trait: ")) .map(|trait_name| trait_name.trim().to_string()) .filter(|trait_name| !trait_name.is_empty()) } /// What `/plot/gemma` validates in a posted GEMMA result: GEMMA's own /// `.assoc` rows are positional, 11 columns wide, with `rs` second and /// `p_lrt` last. fn check_gemma_result(posted: &serde_json::Value) -> Result<(), String> { let rows = posted["data"].as_array().ok_or( "`data` must be the array of GEMMA rows from /compute/gemma -- post that response back, not a request", )?; if rows.is_empty() { return Err("`data` is empty: nothing to plot".to_string()); } let columns = posted["meta"]["columns"] .as_array() .ok_or( "post the whole /compute/gemma response, not just its `data`: the plotter needs `meta.columns` to know which column is `p_lrt`", )?; let names: Vec<&str> = columns.iter().filter_map(|name| name.as_str()).collect(); for needed in ["chr", "rs", "ps", "p_lrt"] { if !names.contains(&needed) { return Err(format!( "meta.columns {names:?} has no '{needed}'; GEMMA rows from lmm 9 are [name, chr, ps, ..., p_lrt]" )); } } let first = rows[0] .as_array() .ok_or("`data` rows must be positional arrays (see meta.columns)")?; if first.len() < names.len() { return Err(format!( "`data` rows have {} columns but meta.columns lists {}", first.len(), names.len() )); } Ok(()) } /// What `/plot/rqtl` validates in a posted R/qtl result: `data.markers`, /// each row `[name, chr, pos, lod, ...]`. fn check_rqtl_result(result: &serde_json::Value) -> Result<(), String> { let rows = result["data"]["markers"] .as_array() .ok_or("`data.markers` must be the R/qtl marker array from /compute/rqtl -- post that response back, not a request")?; if rows.is_empty() { return Err("`data.markers` is empty: nothing to plot".to_string()); } let first = rows[0] .as_array() .ok_or("marker rows must be positional arrays (see meta.columns)")?; if first.len() < 4 { return Err(format!( "marker rows have {} columns; R/qtl rows are [name, chr, pos, lod, ...]", first.len() )); } Ok(()) } /// The document handed to the plotter: the posted response as-is when it /// is a whole envelope, or wrapped when the caller posted only the `data` /// member (the scripts read `data` and `notes`). fn as_plot_document(posted: &serde_json::Value) -> serde_json::Value { if posted.get("data").is_some() { posted.clone() } else { serde_json::json!({"data": posted, "notes": []}) } } #[utoipa::path(post, path = "/plot/rqtl", summary = "Draw the Manhattan (LOD) plot of an R/qtl result, as an SVG", description = "Post the response of POST /compute/rqtl back (as-is, or just its `data` \ member) and get the plot scripts/plot-rqtl.py draws from it: LOD per marker with the \ permutation thresholds as dashed lines when the result carried them. Nothing is recomputed. \ The reply is image/svg+xml, not the JSON envelope, and `x-plot-summary` carries the \ plotter's one-line peak summary.", params(PlotParams), request_body = serde_json::Value, responses( (status = 200, description = "The plot, as image/svg+xml", body = String, content_type = "image/svg+xml"), Unauthorized, (status = 422, description = "The posted body is not an R/qtl result", body = ApiError), (status = 502, description = "The plotter could not run, or failed", body = ApiError) ) )] #[gnauth(token_only)] pub async fn plot_rqtl( ctx: Ctx, _token: AuthToken, Query(plot_params): Query, Json(posted): Json, ) -> Result { let rid = ctx.request_info(); let document = as_plot_document(&posted); if let Err(detail) = check_rqtl_result(&document) { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "not_an_rqtl_result", "Not an R/qtl result", detail, "plot_rqtl", ) .with_request_id(rid)); } let config = Config::load(); let mut extra: Vec = 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.rqtl_plotter, std::path::Path::new(&config.rqtl_cache_dir), &document, plot_params .trait_label .clone() .or_else(|| trait_from_document(&document)) .as_deref() .unwrap_or("rqtl"), &borrowed, ) .await .map_err(|e| { ApiError::new( StatusCode::BAD_GATEWAY, "plot_failed", "Could not draw the plot", e.to_string(), "plot_rqtl", ) .with_request_id(rid.clone()) })?; Ok(svg_response(rendered)) } #[utoipa::path(post, path = "/plot/gemma", summary = "Draw the Manhattan plot of a GEMMA result, as an SVG", description = "Post the response of POST /compute/gemma back (as-is, or just its `data` \ member) and get the plot scripts/plot-gemma.py draws from it: -log10(p_lrt) per marker. \ **No reference line is drawn unless one is asked for** -- a line is an annotation, not part of \ the result, and each is labelled with where it came from: `?bonferroni=true` for GEMMA's own \ Bonferroni (0.05 over the analysed markers, computed by the plotter, conservative under \ linkage and unrelated to relatedness), and `?thresholds=` for a threshold another engine \ computed on the same values (e.g. /compute/bulklmm's rotation thresholds). Nothing is \ recomputed. image/svg+xml, not the JSON envelope; `x-plot-summary` carries the plotter's \ one-line summary, naming the reference lines it drew.", params(PlotParams), request_body = serde_json::Value, responses( (status = 200, description = "The plot, as image/svg+xml", body = String, content_type = "image/svg+xml"), Unauthorized, (status = 422, description = "The posted body is not a GEMMA result", body = ApiError), (status = 502, description = "The plotter could not run, or failed", body = ApiError) ) )] #[gnauth(token_only)] pub async fn plot_gemma( ctx: Ctx, _token: AuthToken, Query(plot_params): Query, Json(posted): Json, ) -> Result { let rid = ctx.request_info(); let document = posted; if let Err(detail) = check_gemma_result(&document) { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "not_a_gemma_result", "Not a GEMMA result", detail, "plot_gemma", ) .with_request_id(rid)); } let config = Config::load(); let mut extra: Vec = Vec::new(); if let Some(title) = plot_params.title.as_deref() { extra.push("--title".to_string()); extra.push(title.to_string()); } if matches!( plot_params.bonferroni.as_deref(), Some("true") | Some("1") | Some("yes") ) { extra.push("--bonferroni".to_string()); } // Thresholds from another engine (`/compute/bulklmm` prints them): drawn on // GEMMA's own scale, labelled, so a reader can see which is which. for (value, label) in external_thresholds( plot_params.thresholds.as_deref(), plot_params.threshold_labels.as_deref(), &rid, )? { extra.push("--threshold".to_string()); extra.push(format!("{value}:{label}")); } let borrowed: Vec<&str> = extra.iter().map(String::as_str).collect(); let rendered = plot::render( &config.plot_python, &config.gemma_plotter, std::path::Path::new(&config.gemma_cache_dir), &document, plot_params .trait_label .clone() .or_else(|| trait_from_document(&document)) .as_deref() .unwrap_or("gemma"), &borrowed, ) .await .map_err(|e| { ApiError::new( StatusCode::BAD_GATEWAY, "plot_failed", "Could not draw the plot", e.to_string(), "plot_gemma", ) .with_request_id(rid.clone()) })?; Ok(svg_response(rendered)) } /// The SVG, with the plotter's summary alongside it. fn svg_response(rendered: plot::Plot) -> Response { let mut response = rendered.svg.into_response(); let headers = response.headers_mut(); headers.insert( header::CONTENT_TYPE, HeaderValue::from_static("image/svg+xml; charset=utf-8"), ); if let Ok(summary) = HeaderValue::from_str(&sanitise_header(&rendered.summary)) { headers.insert("x-plot-summary", summary); } response } /// Header values may not contain newlines or non-visible ASCII; the /// plotter's summary is one line, but this keeps a bad one from becoming a /// 500. fn sanitise_header(text: &str) -> String { text.chars() .map(|c| if c.is_ascii_graphic() || c == ' ' { c } else { ' ' }) .take(500) .collect() } #[cfg(test)] mod tests { use super::sanitise_header; #[test] fn a_summary_with_newlines_survives_as_a_header() { assert_eq!( sanitise_header("wrote out.svg: peak rs1 chr9 29.9 Mb LOD 4.20\n"), "wrote out.svg: peak rs1 chr9 29.9 Mb LOD 4.20 " ); } } #[derive(Deserialize, utoipa::ToSchema)] pub struct GenotypePlot { /// The marker the calls are at, for the title. pub marker: String, /// Individual -> genotype call, as the peak-genotypes reply gives it. The /// short form (`{"BXD1": "B"}`) or the reply's `animals` rows both work. #[schema(value_type = Object)] pub genotypes: serde_json::Value, /// The trait's values: `/groups/{group}/traits/{id}/values` rows, or a /// name -> value map. #[schema(value_type = Object)] pub values: serde_json::Value, } /// Points as `{individual, genotype, value}` from the two shapes a caller has: /// the peak-genotypes reply and the trait's values. fn genotype_points( genotypes: &serde_json::Value, values: &serde_json::Value, ) -> Vec { let mut calls: std::collections::BTreeMap = std::collections::BTreeMap::new(); match genotypes { serde_json::Value::Object(map) => { for (name, call) in map { if let Some(call) = call.as_str() { calls.insert(name.clone(), call.to_string()); } } } serde_json::Value::Array(rows) => { for row in rows { if let (Some(name), Some(call)) = ( row.get("individual").and_then(|v| v.as_str()), row.get("genotype").and_then(|v| v.as_str()), ) { calls.insert(name.to_string(), call.to_string()); } } } _ => {} } let mut numbers: std::collections::BTreeMap = std::collections::BTreeMap::new(); match values { serde_json::Value::Object(map) => { for (name, value) in map { if let Some(value) = value.as_f64() { numbers.insert(name.clone(), value); } } } serde_json::Value::Array(rows) => { for row in rows { if let (Some(name), Some(value)) = ( row.get("name").and_then(|v| v.as_str()), row.get("value").and_then(|v| v.as_f64()), ) { numbers.insert(name.to_string(), value); } } } _ => {} } calls .into_iter() .filter_map(|(individual, genotype)| { let value = *numbers.get(&individual)?; Some(serde_json::json!({ "individual": individual, "genotype": genotype, "value": value, })) }) .collect() } #[utoipa::path(post, path = "/plot/genotypes", summary = "Draw a trait by genotype class at one marker, as an SVG", description = "Post the data from `/groups/{group}/traits/{id}/peak-genotypes` with the \ trait's values (from `/groups/{group}/traits/{id}/values`) and get R/qtl's Fig 4.1 drawn: one \ point per animal, x its genotype at the marker, y its value, with the class means. Nothing is \ recomputed -- the plot is of the numbers you send. image/svg+xml, not the JSON envelope.", request_body = GenotypePlot, responses( (status = 200, description = "The plot, as image/svg+xml", body = String, content_type = "image/svg+xml"), Unauthorized, (status = 422, description = "No point has both a call and a value", body = ApiError), (status = 502, description = "The plotter could not run, or failed", body = ApiError) ) )] #[gnauth(token_only)] pub async fn plot_genotypes( ctx: Ctx, _token: AuthToken, Json(request): Json, ) -> Result { let rid = ctx.request_info(); let points = genotype_points(&request.genotypes, &request.values); if points.is_empty() { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "no_points", "Nothing to plot", "no individual has both a genotype call and a value; post the peak-genotypes \ reply's `animals` (or its `genotypes`) together with the trait's values." .to_string(), "plot_genotypes", ) .with_request_id(rid)); } let config = Config::load(); let document = serde_json::json!({ "marker": request.marker, "points": points, }); let rendered = plot::render( &config.plot_python, &config.genotype_plotter, std::path::Path::new(&config.rqtl_cache_dir), &document, &request.marker, &[], ) .await .map_err(|error| { ApiError::new( StatusCode::BAD_GATEWAY, "plot_failed", "Could not draw the plot", error.to_string(), "plot_genotypes", ) .with_request_id(rid.clone()) })?; Ok(svg_response(rendered)) } /// What `/plot/bnw` validates in a posted BNW result: positional rows whose /// `meta.columns` name the edge, the shape `/compute/bnw` returns. fn check_bnw_result(result: &serde_json::Value) -> Result<(), String> { let rows = result .get("data") .and_then(|data| data.as_array()) .ok_or("the posted body has no `data` array of rows")?; if rows.is_empty() { return Err("the posted body has no rows".to_string()); } let columns: Vec<&str> = result .get("meta") .and_then(|meta| meta.get("columns")) .and_then(|columns| columns.as_array()) .map(|columns| columns.iter().filter_map(|c| c.as_str()).collect()) .unwrap_or_default(); if columns.len() < 3 || columns.get(0) != Some(&"from") || columns.get(1) != Some(&"to") { return Err(format!( "expected the columns of /compute/bnw (from, to, posterior, in_structure), got \ {columns:?}" )); } Ok(()) } #[utoipa::path(post, path = "/plot/bnw", summary = "Draw a BNW network, as an SVG", description = "Post the response of POST /compute/bnw back (as-is) and get the figure \ scripts/plot-bnw.py draws from it: the learned structure with one arrow per edge that survived \ the threshold, arrow width and label = the edge's posterior, and the below-threshold edges as \ faint dotted lines so a reader sees what was considered as well as what survived. \ `?kind=posterior` draws every candidate edge as a cell in a matrix instead, which is where a \ reader sees how close an edge came to the threshold. Nothing is recomputed. 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 is not a BNW result, or `kind` is not one of network/posterior", body = ApiError), (status = 502, description = "The plotter failed", body = ApiError) ) )] #[gnauth(token_only)] pub async fn plot_bnw( ctx: Ctx, _token: AuthToken, Query(plot_params): Query, Json(posted): Json, ) -> Result { let rid = ctx.request_info(); if let Err(detail) = check_bnw_result(&posted) { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "not_a_bnw_result", "Not a BNW result", detail, "plot_bnw", ) .with_request_id(rid)); } let config = Config::load(); let mut extra: Vec = Vec::new(); if let Some(title) = plot_params.title.as_deref() { extra.push("--title".to_string()); extra.push(title.to_string()); } if let Some(kind) = plot_params.kind.as_deref() { let kind = kind.trim().to_ascii_lowercase(); if kind != "network" && kind != "posterior" { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "invalid_kind", "Unknown figure", format!("kind must be `network` or `posterior`, not {kind:?}.", ), "plot_bnw", ) .with_request_id(rid)); } extra.push("--kind".to_string()); extra.push(kind); } let borrowed: Vec<&str> = extra.iter().map(String::as_str).collect(); let rendered = plot::render( &config.plot_python, &config.bnw_plotter, std::path::Path::new(&config.bnw_cache_dir), &posted, plot_params .trait_label .clone() .or_else(|| trait_from_document(&posted)) .as_deref() .unwrap_or("BNW"), &borrowed, ) .await .map_err(|error| { ApiError::new( StatusCode::BAD_GATEWAY, "plot_failed", "Could not draw the plot", error.to_string(), "plot_bnw", ) .with_request_id(rid.clone()) })?; Ok(svg_response(rendered)) } /// What `/plot/bulklmm` validates in a posted BulkLMM result: positional rows /// whose `meta.columns` carry a LOD, the shape `/compute/bulklmm` returns. fn check_bulklmm_result(result: &serde_json::Value) -> Result<(), String> { let rows = result .get("data") .and_then(|data| data.as_array()) .ok_or("the posted body has no `data` array of rows")?; if rows.is_empty() { return Err("the posted body has no rows".to_string()); } let columns: Vec<&str> = result .get("meta") .and_then(|meta| meta.get("columns")) .and_then(|columns| columns.as_array()) .map(|columns| columns.iter().filter_map(|c| c.as_str()).collect()) .unwrap_or_default(); if columns.len() < 4 || columns.get(3) != Some(&"lod") { return Err(format!( "expected the columns of /compute/bulklmm (marker, chr, pos, lod, …), got {columns:?}" )); } Ok(()) } #[utoipa::path(post, path = "/plot/bulklmm", summary = "Draw a BulkLMM scan, as an SVG", description = "Post the response of POST /compute/bulklmm back (as-is) and get the LOD plot \ scripts/plot-bulklmm.py draws from it, with the permutation thresholds the reply's own `notes` \ carry (alpha 0.05 genome-wide, alpha 0.01) drawn as dashed lines. Nothing is recomputed. \ image/svg+xml, not the JSON envelope; `x-plot-summary` carries the plotter's one-line peak \ summary.", params(PlotParams), request_body = serde_json::Value, responses( (status = 200, description = "The plot, as image/svg+xml", body = String, content_type = "image/svg+xml"), Unauthorized, (status = 422, description = "The posted body is not a BulkLMM result", body = ApiError), (status = 502, description = "The plotter could not run, or failed", body = ApiError) ) )] #[gnauth(token_only)] pub async fn plot_bulklmm( ctx: Ctx, _token: AuthToken, Query(plot_params): Query, Json(posted): Json, ) -> Result { let rid = ctx.request_info(); if let Err(detail) = check_bulklmm_result(&posted) { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "not_a_bulklmm_result", "Not a BulkLMM result", detail, "plot_bulklmm", ) .with_request_id(rid)); } let config = Config::load(); let mut extra: Vec = Vec::new(); if let Some(title) = plot_params.title.as_deref() { extra.push("--title".to_string()); extra.push(title.to_string()); } if matches!( plot_params.all_thresholds.as_deref(), Some("true") | Some("1") | Some("yes") | Some("all") ) { extra.push("--all-thresholds".to_string()); } for (value, label) in external_thresholds( plot_params.thresholds.as_deref(), plot_params.threshold_labels.as_deref(), &rid, )? { extra.push("--threshold".to_string()); extra.push(format!("{value}:{label}")); } let borrowed: Vec<&str> = extra.iter().map(String::as_str).collect(); let rendered = plot::render( &config.plot_python, &config.bulklmm_plotter, std::path::Path::new(&config.bulklmm_cache_dir), &posted, plot_params .trait_label .clone() .or_else(|| trait_from_document(&posted)) .as_deref() .unwrap_or("bulklmm"), &borrowed, ) .await .map_err(|error| { ApiError::new( StatusCode::BAD_GATEWAY, "plot_failed", "Could not draw the plot", error.to_string(), "plot_bulklmm", ) .with_request_id(rid.clone()) })?; Ok(svg_response(rendered)) } #[utoipa::path(post, path = "/plot/pca", summary = "Draw the scree plot of a correlation-matrix PCA, as an SVG", description = "Post the response of POST /compute/correlation/matrix back (as-is) after \ asking it for `\"pca\": true`, and get the figure scripts/plot-pca.py draws from it: one bar per \ component for its share of the variance, a cumulative line so a reader can see how many \ components carry the signal, and the traits the PCA had to drop for gaps. GN2 draws the same \ figure client-side with Plotly; this is the same numbers as a file. Nothing is recomputed. \ 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 pca components", body = ApiError), (status = 502, description = "The plotter failed", body = ApiError) ) )] #[gnauth(token_only)] pub async fn plot_pca( ctx: Ctx, _token: AuthToken, Query(plot_params): Query, Json(posted): Json, ) -> Result { let rid = ctx.request_info(); if let Err(detail) = check_pca_result(&posted) { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "not_a_pca_result", "Not a PCA result", detail, "plot_pca", ) .with_request_id(rid)); } let config = Config::load(); let mut extra: Vec = Vec::new(); if let Some(title) = plot_params.title.as_deref() { extra.push("--title".to_string()); extra.push(title.to_string()); } if let Some(kind) = plot_params.kind.as_deref() { // `--max-components N`, so a 200-trait matrix does not draw 200 bars. let n: usize = kind.trim().parse().map_err(|_| { ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "invalid_kind", "Unknown figure", format!("kind must be a number of components to draw, not {kind:?}"), "plot_pca", ) .with_request_id(rid.clone()) })?; extra.push("--max-components".to_string()); extra.push(n.to_string()); } let borrowed: Vec<&str> = extra.iter().map(String::as_str).collect(); let rendered = plot::render( &config.plot_python, &config.pca_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_pca", ) .with_request_id(rid) })?; 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, Json(posted): Json, ) -> Result { 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 = 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 .get("data") .and_then(|data| data.get("pca")) .or_else(|| result.get("pca")) .ok_or("the posted body has no `pca` object: ask /compute/correlation/matrix for \ \"pca\": true first")?; let components = pca .get("components") .and_then(|components| components.as_array()) .ok_or("`pca.components` is missing")?; if components.is_empty() { return Err("`pca.components` is empty -- the PCA had nothing to decompose".to_string()); } if components.len() < 2 { return Err("a scree plot needs at least two components".to_string()); } Ok(()) }