diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/config.rs | 9 | ||||
| -rw-r--r-- | src/lib.rs | 2 | ||||
| -rw-r--r-- | src/routes/mod.rs | 1 | ||||
| -rw-r--r-- | src/routes/peakgenotypes.rs | 411 | ||||
| -rw-r--r-- | src/routes/plot.rs | 136 | ||||
| -rw-r--r-- | src/routes/rqtl.rs | 15 |
6 files changed, 568 insertions, 6 deletions
diff --git a/src/config.rs b/src/config.rs index b0ab030..21ca891 100644 --- a/src/config.rs +++ b/src/config.rs @@ -146,6 +146,8 @@ pub struct Config { /// Directory holding one SQLite file per user's baskets (`BASKET_DIR`), /// named by a hash of the token's subject. See src/baskets.rs. pub basket_dir: String, + /// The script that draws a trait by genotype class (`GENOTYPE_PLOTTER`). + pub genotype_plotter: String, /// Directory holding the genotype files (`GENOTYPE_FILES`): GN2's /// layout -- `genotype/<Group>.json` for the version list, /// `genotype/<stem>.geno`, `genotype/bimbam/<stem>_geno.txt` and @@ -309,6 +311,10 @@ impl Config { "https://query.wikidata.org/sparql".to_string(), ); values.insert("WIKIDATA_TTL_SECONDS".to_string(), "604800".to_string()); + values.insert( + "GENOTYPE_PLOTTER".to_string(), + "scripts/plot-genotypes.py".to_string(), + ); // Per-user baskets: one SQLite file each (src/baskets.rs). Never // MariaDB -- a user's edited column is theirs. values.insert( @@ -372,6 +378,7 @@ impl Config { "WIKIDATA_ENDPOINT", "WIKIDATA_TTL_SECONDS", "BASKET_DIR", + "GENOTYPE_PLOTTER", ] { if let Ok(value) = std::env::var(key) { values.insert(key.to_string(), value); @@ -417,6 +424,7 @@ impl Config { wikidata_endpoint: values["WIKIDATA_ENDPOINT"].clone(), wikidata_ttl: values["WIKIDATA_TTL_SECONDS"].parse().unwrap_or(604800), basket_dir: values["BASKET_DIR"].clone(), + genotype_plotter: values["GENOTYPE_PLOTTER"].clone(), genotype_files_dir: values["GENOTYPE_FILES"].clone(), sql_check_health: parse_switch(&values["SQL_CHECK_HEALTH"]), rqtl_max_concurrent: values["RQTL_MAX_CONCURRENT"] @@ -665,6 +673,7 @@ mod tests { "WIKIDATA_ENDPOINT", "WIKIDATA_TTL_SECONDS", "BASKET_DIR", + "GENOTYPE_PLOTTER", ] { if std::env::var(key).is_ok() { eprintln!("skipping: {key} is set in the environment"); diff --git a/src/lib.rs b/src/lib.rs index 3518de6..c163238 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -130,6 +130,7 @@ pub fn app() -> Router { .routes(routes!(routes::baskets::basket_revisions)) .routes(routes!(routes::baskets::revise_basket)) .routes(routes!(routes::baskets::delete_basket)) + .routes(routes!(routes::peakgenotypes::peak_genotypes)) .routes(routes!(routes::genoupload::upload_genotype)) .routes(routes!(routes::genoupload::list_genotypes)) .routes(routes!(routes::genoupload::get_genotype)) @@ -146,6 +147,7 @@ pub fn app() -> Router { .routes(routes!(routes::probesets::gene_aliases)) .routes(routes!(routes::plot::plot_rqtl)) .routes(routes!(routes::plot::plot_gemma)) + .routes(routes!(routes::plot::plot_genotypes)) .routes(routes!(routes::phewas::group_phewas)) .routes(routes!(routes::frequencies::group_version_frequencies)) .routes(routes!(routes::frequencies::group_marker_frequencies)) diff --git a/src/routes/mod.rs b/src/routes/mod.rs index 3fbbcea..15f57ce 100644 --- a/src/routes/mod.rs +++ b/src/routes/mod.rs @@ -16,6 +16,7 @@ pub mod genotypes; pub mod groups; pub mod mapping_methods; pub mod matrices; +pub mod peakgenotypes; pub mod phewas; pub mod plot; pub mod probesets; diff --git a/src/routes/peakgenotypes.rs b/src/routes/peakgenotypes.rs new file mode 100644 index 0000000..649dc0e --- /dev/null +++ b/src/routes/peakgenotypes.rs @@ -0,0 +1,411 @@ +//! `GET /groups/{group}/traits/{trait_id}/peak-genotypes`: the genotypes of the +//! animals at one marker of a **confirmed** hit. +//! +//! Returning genotypes is the one thing this API otherwise never does, so it +//! is fenced: the marker has to be at the peak of a scan the server just ran, +//! the peak has to clear a LOD threshold, and only animals that have a value +//! for that trait get a call. That is exactly what is needed to draw a trait by +//! genotype class (R/qtl's book, Fig 4.1) and nothing more -- the rest of the +//! matrix stays where it is. +//! +//! The scan is re-run rather than trusted: a client naming a marker is asking +//! the server to confirm the hit, so `/compute/rqtl`'s own machinery runs over +//! the group's current (or named) version and the peak is measured here. + +use axum::Json; +use axum::extract::{Path, Query}; +use axum::http::StatusCode; +use serde::Deserialize; +use serde_json::Value; + +use gnauth_macros::{compute_gate, gnauth}; + +use crate::auth::AuthToken; +use crate::compute_gate as gate; +use crate::config::Config; +use crate::error::{ApiError, Unauthorized}; +use crate::frequencies; +use crate::genotypes; +use crate::response::{Ctx, Envelope, RequestInfo}; +use crate::rqtl::{self, Sample}; + +#[derive(Deserialize, utoipa::IntoParams)] +pub struct PeakGenotypeParams { + /// The marker to return calls for -- typically the peak the mapping found. + pub marker: String, + /// How far (Mb) the marker may sit from the scan's own peak. Default 10. + pub window: Option<f64>, + /// The LOD the peak must reach. Default 3.0: below this there is no hit to + /// confirm. + pub min_lod: Option<f64>, + /// The genotype version, default the group's current one. + pub genotype_version: Option<String>, +} + +/// One animal at the marker. +#[derive(serde::Serialize, utoipa::ToSchema)] +pub struct CalledAnimal { + pub individual: String, + /// The call as the genotype file spells it (`B`, `D`, `H`, …). + pub genotype: String, + /// Its value for the trait, on the trait's own scale. + pub value: f64, +} + +#[utoipa::path(get, path = "/groups/{group}/traits/{trait_id}/peak-genotypes", + summary = "Genotypes at one marker of a confirmed hit, for animals with a value", + description = "Returns the genotype call of each animal **that has a value for this trait** \ +at one marker -- the data behind a trait-by-genotype plot. It is fenced: the server re-runs \ +the R/qtl scan for the trait, and the marker is only answered if it lies within `window` Mb of \ +that scan's peak and the peak reaches `min_lod`. No other genotypes are returned, and nothing \ +of the matrix beyond these calls.", + params( + ("group" = String, Path, description = "InbredSet name, e.g. DOL"), + ("trait_id" = u32, Path, description = "Trait id within the group"), + PeakGenotypeParams + ), + responses( + (status = 200, description = "The marker, its scan statistics, and one call per animal with a value", body = Envelope<Value>), + Unauthorized, + (status = 403, description = "The trait is not public and you are not authorized", body = ApiError), + (status = 404, description = "No such group, trait, version or marker", body = ApiError), + (status = 422, description = "The marker is not at a confirmed hit", body = ApiError) + ) +)] +#[gnauth(secured)] +#[compute_gate(rqtl, label = "peak genotypes")] +pub async fn peak_genotypes( + ctx: Ctx, + token: AuthToken, + Path((group, trait_id)): Path<(String, u32)>, + Query(params): Query<PeakGenotypeParams>, +) -> Result<Json<Envelope<Value>>, ApiError> { + let rid = ctx.request_info(); + let config = Config::load(); + let marker = params.marker.clone(); + let window = params.window.unwrap_or(10.0).abs(); + let min_lod = params.min_lod.unwrap_or(3.0); + + // The trait's values, with its own authorization. + let auth_server_url = config.auth_server_url.clone(); + let group_for_values = group.clone(); + let values = tokio::task::spawn_blocking(move || { + crate::routes::groups::get_group_trait_values_result( + &group_for_values, + trait_id, + &auth_server_url, + &token, + ) + }) + .await + .map_err(|error| internal(error.to_string(), rid.clone()))?; + let values = match values { + Ok(crate::routes::groups::GroupTraitLookup::Found(authorized, values)) => { + let _: crate::auth::Authorized = authorized; + values + } + Ok(crate::routes::groups::GroupTraitLookup::Forbidden) => { + return Err(ApiError::new( + StatusCode::FORBIDDEN, + "forbidden", + "Not authorized", + format!("trait {trait_id} is not public, and you are not authorized to view it."), + "peak_genotypes", + ) + .with_request_id(rid)); + } + Ok(crate::routes::groups::GroupTraitLookup::GroupNotFound) => { + return Err(ApiError::new( + StatusCode::NOT_FOUND, + "group_not_found", + "Group not found", + format!("No group matching '{group}'."), + "peak_genotypes", + ) + .with_request_id(rid)); + } + Ok(crate::routes::groups::GroupTraitLookup::TraitNotFound) => { + return Err(ApiError::new( + StatusCode::NOT_FOUND, + "trait_not_found", + "Trait not found", + format!("No trait {trait_id} in group '{group}'."), + "peak_genotypes", + ) + .with_request_id(rid)); + } + Err(crate::routes::groups::GroupAuthError::Db(error)) => { + return Err(ApiError::from_db(error, "peak_genotypes").with_request_id(rid)) + } + Err(crate::routes::groups::GroupAuthError::Auth(detail)) => { + return Err(ApiError::new( + StatusCode::BAD_GATEWAY, + "auth_server_error", + "Could not check authorization", + detail, + "peak_genotypes", + ) + .with_request_id(rid)); + } + }; + let samples: Vec<Sample> = values + .iter() + .map(|value| Sample { + name: value.name.clone(), + value: value.value, + }) + .collect(); + let trait_label = format!("{group}::{trait_id}"); + + // The scan: the same path /compute/rqtl takes for a group request. + let directory = config.genotype_files_dir.clone(); + let cache_dir = config.rqtl_cache_dir.clone(); + let wrapper = config.rqtl_wrapper_path.clone(); + let group_for_scan = group.clone(); + let version = params.genotype_version.clone(); + let values_by_name: Vec<(String, Option<f64>)> = samples + .iter() + .map(|sample| (sample.name.clone(), sample.value)) + .collect(); + let values_for_scan = values_by_name.clone(); + let cache_dir_for_scan = cache_dir.clone(); + let trait_for_scan = trait_label.clone(); + let scan = tokio::task::spawn_blocking(move || { + let resolved = + genotypes::resolve(std::path::Path::new(&directory), &group_for_scan, version.as_deref()) + .map_err(|error| error.to_string())?; + let excluded = genotypes::non_strains( + std::path::Path::new(&directory), + &group_for_scan, + &resolved.panel, + ); + let keep: Vec<usize> = resolved + .panel + .iter() + .enumerate() + .filter(|(_, name)| !excluded.contains(*name)) + .map(|(index, _)| index) + .collect(); + let (aligned, _matched) = genotypes::align(&resolved.panel, &keep, &values_for_scan); + let prepared = genotypes::prepare( + std::path::Path::new(&directory), + &resolved, + genotypes::Engine::Rqtl, + &keep, + std::path::Path::new(&cache_dir_for_scan), + ) + .map_err(|error| error.to_string())?; + let names: Vec<String> = keep.iter().map(|index| resolved.panel[*index].clone()).collect(); + let samples: Vec<Sample> = names + .into_iter() + .zip(aligned) + .map(|(name, value)| Sample { name, value }) + .collect(); + Ok::<_, String>((resolved.geno.clone(), resolved.version.clone(), prepared, samples)) + }) + .await + .map_err(|error| internal(error.to_string(), rid.clone()))? + .map_err(|error| { + ApiError::new( + StatusCode::UNPROCESSABLE_ENTITY, + "genotype_error", + "The genotype files could not be read", + error, + "peak_genotypes", + ) + .with_request_id(rid.clone()) + })?; + let (geno, version_used, prepared, mapped_samples) = scan; + let prepared_genotype_file = prepared.genotype_file.to_string_lossy().into_owned(); + + let output = rqtl::compute( + &wrapper, + &cache_dir, + &prepared_genotype_file, + &trait_for_scan, + &mapped_samples, + &[], + "normal", + "hk", + 0, + "Mb", + None, + None, + ) + .await + .map_err(|error| { + ApiError::new( + StatusCode::BAD_GATEWAY, + "rqtl_failed", + "R/qtl computation failed", + error.to_string(), + "peak_genotypes", + ) + .with_request_id(rid.clone()) + })?; + + let Some(peak) = output.markers.iter().max_by(|left, right| { + left.lod.partial_cmp(&right.lod).unwrap_or(std::cmp::Ordering::Equal) + }) else { + return Err(ApiError::new( + StatusCode::UNPROCESSABLE_ENTITY, + "no_scan", + "The scan produced no markers", + "the genotype version has nothing to scan".to_string(), + "peak_genotypes", + ) + .with_request_id(rid)); + }; + if peak.lod < min_lod { + return Err(ApiError::new( + StatusCode::UNPROCESSABLE_ENTITY, + "not_a_hit", + "No confirmed hit to report", + format!( + "this trait's strongest marker is {} (chr{}, {:.2} Mb) at LOD {:.2}, below the \ + {min_lod} needed to confirm a hit", + peak.name, peak.chr, peak.pos, peak.lod + ), + "peak_genotypes", + ) + .with_request_id(rid)); + } + // The marker has to be at *this* peak: a far-away marker is not covered by + // whatever the scan confirmed. + let Some(requested) = output + .markers + .iter() + .find(|candidate| candidate.name == marker) + else { + return Err(ApiError::new( + StatusCode::NOT_FOUND, + "marker_not_found", + "Marker not in this scan", + format!("no marker '{marker}' in the scan of {group}'s genotype version"), + "peak_genotypes", + ) + .with_request_id(rid)); + }; + let distance = if requested.chr == peak.chr { + (requested.pos - peak.pos).abs() + } else { + f64::INFINITY + }; + if distance > window { + return Err(ApiError::new( + StatusCode::UNPROCESSABLE_ENTITY, + "not_the_peak", + "That marker is not at the confirmed peak", + format!( + "the scan peaks at {} (chr{}, {:.2} Mb, LOD {:.2}); {marker} is {distance:.1} Mb \ + away{}. Genotypes are only returned at a confirmed hit", + peak.name, + peak.chr, + peak.pos, + peak.lod, + if distance.is_finite() { + String::new() + } else { + format!(" (chromosome {})", requested.chr) + } + ), + "peak_genotypes", + ) + .with_request_id(rid)); + } + + // The calls, for the animals that have a value. Nothing else leaves. + let geno_path = geno.clone(); + let wanted_marker = marker.clone(); + let calls = tokio::task::spawn_blocking(move || { + frequencies::marker_calls(&geno_path, &wanted_marker) + }) + .await + .map_err(|error| internal(error.to_string(), rid.clone()))? + .map_err(|error| { + ApiError::new( + StatusCode::NOT_FOUND, + "marker_not_found", + "Marker not found", + error.to_string(), + "peak_genotypes", + ) + .with_request_id(rid.clone()) + })?; + let by_name: std::collections::HashMap<&str, Option<f64>> = samples + .iter() + .map(|sample| (sample.name.as_str(), sample.value)) + .collect(); + let mut animals: Vec<CalledAnimal> = Vec::new(); + for (individual, call) in &calls.calls { + let (Some(call), Some(Some(value))) = (call, by_name.get(individual.as_str())) else { + continue; + }; + animals.push(CalledAnimal { + individual: individual.clone(), + genotype: call.clone(), + value: *value, + }); + } + if animals.is_empty() { + return Err(ApiError::new( + StatusCode::UNPROCESSABLE_ENTITY, + "no_called_animals", + "No animal with a value carries a call here", + format!("marker {marker} has no calls for the animals with a value for this trait"), + "peak_genotypes", + ) + .with_request_id(rid)); + } + let mut counts: std::collections::BTreeMap<String, usize> = std::collections::BTreeMap::new(); + for animal in &animals { + *counts.entry(animal.genotype.clone()).or_insert(0) += 1; + } + let mut envelope = ctx + .envelope(serde_json::json!({ + "marker": marker, + "chr": requested.chr, + "pos": requested.pos, + "lod": (requested.lod * 1000.0).round() / 1000.0, + "peak": {"marker": peak.name, "chr": peak.chr, "pos": peak.pos, + "lod": (peak.lod * 1000.0).round() / 1000.0}, + "window_mb": window, + "genotype_version": version_used, + "counts": counts, + "animals": animals, + })) + .with_note(&format!( + "Confirmed by a scan this request ran: {group}'s genotype version {} peaks at {} \ + (chr{}, {:.2} Mb) with LOD {:.2}, and {marker} is {:.1} Mb from it.", + version_used, peak.name, peak.chr, peak.pos, peak.lod, distance + )) + .with_note( + "Only animals that have a value for this trait are listed, and only this marker's \ + calls -- the rest of the genotype matrix is not returned. Widen the confirmation \ + with ?window= (Mb) or ?min_lod=; a marker away from the peak is refused.", + ); + envelope = envelope.with_action(crate::response::SuggestedCall { + method: "POST".to_string(), + href: "/plot/genotypes".to_string(), + description: "Draw the trait by genotype class: post this reply's data with the trait's \ + values (see `next`)." + .to_string(), + body: None, + }); + envelope = envelope.with_next( + &format!("/groups/{}/traits/{trait_id}/values", crate::response::path_segment(&group)), + "The trait's values, to post with this reply to /plot/genotypes", + ); + Ok(Json(envelope)) +} + +fn internal(message: String, rid: RequestInfo) -> ApiError { + ApiError::new( + StatusCode::INTERNAL_SERVER_ERROR, + "internal_error", + "Internal error", + message, + "peak_genotypes", + ) + .with_request_id(rid) +} diff --git a/src/routes/plot.rs b/src/routes/plot.rs index 00119dc..f386526 100644 --- a/src/routes/plot.rs +++ b/src/routes/plot.rs @@ -299,3 +299,139 @@ mod tests { ); } } + +#[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<serde_json::Value> { + let mut calls: std::collections::BTreeMap<String, String> = 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<String, f64> = 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<GenotypePlot>, +) -> Result<Response, ApiError> { + 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)) +} diff --git a/src/routes/rqtl.rs b/src/routes/rqtl.rs index 5bb227c..065b034 100644 --- a/src/routes/rqtl.rs +++ b/src/routes/rqtl.rs @@ -237,7 +237,15 @@ pub async fn compute_rqtl( ); } let samples: Vec<RqtlSample> = request.samples.take().unwrap_or_default(); - if samples.is_empty() { + let request_genotype_file = request.genotype_file.clone(); + let request_genotype_version = request.genotype_version.clone(); + let request_nperm = request.nperm.unwrap_or(0); + let request_model = request.model.clone().unwrap_or_else(|| "normal".to_string()); + let request_method = request.method.clone().unwrap_or_else(|| "hk".to_string()); + // A request naming both a group and a file is answered as ambiguous even + // when it also forgot its values: the input is the first thing to fix. + let both_inputs = request.genotype_file.is_some() && request.group.is_some(); + if samples.is_empty() && !both_inputs { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "missing_samples", @@ -248,11 +256,6 @@ pub async fn compute_rqtl( ) .with_request_id(rid)); } - let request_genotype_file = request.genotype_file.clone(); - let request_genotype_version = request.genotype_version.clone(); - let request_nperm = request.nperm.unwrap_or(0); - let request_model = request.model.clone().unwrap_or_else(|| "normal".to_string()); - let request_method = request.method.clone().unwrap_or_else(|| "hk".to_string()); // The caller's own named values, kept to rebuild a runnable body for // the permutation suggestion below (the aligned panel-length vector // would be thousands of entries on a real panel). |
