//! QTL-mapping suggestions for the per-trait values endpoints. //! //! Fetching one trait's value per strain is usually the step before //! mapping that trait, and the API can do the mapping itself //! (`/compute/rqtl`, `/compute/gemma`). Those are `POST`s with a body, so //! they cannot go in `next` -- following a `next` link is a `GET` that //! returns 200, which is what makes `next` safe to follow blindly -- hence //! [`SuggestedCall`] in the envelope's `actions`. //! //! What the server can fill in, it does: the values themselves, in the //! sample order of the response they came from. What it cannot know is //! where the genotype files live on its own filesystem, so those stay //! bracketed placeholders: a caller that posts the body unchanged gets a //! clear "no such file" error rather than a wrong answer. use crate::response::SuggestedCall; /// The two per-strain value types (`db::TraitValue`, `db::ProbeSetValue`) /// are both `{name, value}`; this is what lets one suggestion builder /// serve both. pub trait NamedValue { fn name(&self) -> &str; fn value(&self) -> Option; } impl NamedValue for crate::db::TraitValue { fn name(&self) -> &str { &self.name } fn value(&self) -> Option { self.value } } impl NamedValue for crate::db::ProbeSetValue { fn name(&self) -> &str { &self.name } fn value(&self) -> Option { self.value } } /// [`mapping_actions_for_group`] for one of the two value types. pub fn mapping_actions_for_group_of( values: &[T], trait_name: &str, group: Option<&str>, normalization: Option<&crate::normalize::Pipeline>, ) -> Vec { let samples: Vec<(String, Option)> = values .iter() .map(|value| (value.name().to_string(), value.value())) .collect(); mapping_actions_for_group_with(&samples, trait_name, group, normalization) } /// [`mapping_actions`] for one of the two value types. pub fn mapping_actions_for(values: &[T], trait_name: &str) -> Vec { let samples: Vec<(String, Option)> = values .iter() .map(|value| (value.name().to_string(), value.value())) .collect(); mapping_actions(&samples, trait_name) } /// Placeholder for a path that must already exist on the server. const SERVER_PATH: &str = ""; /// `POST /compute/rqtl` and `POST /compute/gemma` for one trait's /// values, in the response's own sample order. /// /// `samples` is `(strain name, value)`; `trait_name` labels the trait in /// the R/qtl request (R/qtl has no other use for it, but a run should be /// identifiable). pub fn mapping_actions(samples: &[(String, Option)], trait_name: &str) -> Vec { mapping_actions_for_group(samples, trait_name, None) } /// [`mapping_actions`], naming the group when the caller knows it: with a /// group the server resolves the genotype file itself /// (`/groups/{group}/genotypes`), so the suggested body needs no paths at /// all. pub fn mapping_actions_for_group( samples: &[(String, Option)], trait_name: &str, group: Option<&str>, ) -> Vec { mapping_actions_for_group_with(samples, trait_name, group, None) } /// [`mapping_actions_for_group`], carrying a normalisation pipeline through /// into the suggested bodies: a caller normalised the values they fetched, /// so the mapping that follows must use the same pipeline or it maps /// different numbers than the response showed. pub fn mapping_actions_for_group_with( samples: &[(String, Option)], trait_name: &str, group: Option<&str>, normalization: Option<&crate::normalize::Pipeline>, ) -> Vec { let values: Vec> = samples.iter().map(|(_, value)| *value).collect(); let named: Vec = samples .iter() .map(|(name, value)| serde_json::json!({"name": name, "value": value})) .collect(); vec![ SuggestedCall { method: "POST".to_string(), href: "/compute/rqtl".to_string(), description: match group { Some(group) => format!( "Map '{trait_name}' with R/qtl (scanone) over {group}'s current genotype \ file: this body carries the {n} values above as `samples`, matched onto \ the panel by name. Synchronous: seconds to minutes.", n = samples.len() ), None => format!( "Map '{trait_name}' with R/qtl (scanone): this body carries the {n} values \ above as `samples`. Add the `group` it belongs to (see \ /groups/{{group}}/genotypes) so the server resolves the genotype file, \ or replace `genotype_file` with a path the server can read. Synchronous: \ seconds to minutes.", n = samples.len() ), }, body: Some(with_normalization( match group { Some(group) => serde_json::json!({ "group": group, "trait_name": trait_name, "samples": named, }), None => serde_json::json!({ "genotype_file": SERVER_PATH, "trait_name": trait_name, "samples": named, }), }, normalization, )), }, SuggestedCall { method: "POST".to_string(), href: "/compute/gemma".to_string(), description: match group { Some(group) => format!( "Run GEMMA's LOCO GWAS on '{trait_name}' over {group}'s current genotype \ file: this body carries the {n} values above as named `samples`, matched \ onto the panel. Synchronous: tens of seconds to minutes, so pass `?id=` \ and poll its status endpoint.", n = samples.len() ), None => format!( "Run GEMMA's LOCO GWAS on '{trait_name}': this body carries the {n} values \ above. Add the `group` it belongs to (see /groups/{{group}}/genotypes) so \ the server resolves the genotype and SNP files, or replace the \ `genotype_file`/`snps_file` placeholders with paths the server can read. \ Synchronous: tens of seconds to minutes, so pass `?id=` and poll its \ status endpoint.", n = samples.len() ), }, body: Some(with_normalization( match group { Some(group) => serde_json::json!({ "group": group, "trait_name": trait_name, "samples": named, }), None => serde_json::json!({ "genotype_file": SERVER_PATH, "snps_file": SERVER_PATH, "trait_values": values, }), }, normalization, )), }, ] } #[cfg(test)] mod tests { use super::*; fn samples() -> Vec<(String, Option)> { vec![ ("BXD1".to_string(), Some(9.5)), ("BXD2".to_string(), None), ] } #[test] fn both_mapping_endpoints_are_suggested_with_the_values_in_order() { let actions = mapping_actions(&samples(), "mytrait"); assert_eq!(actions.len(), 2); assert_eq!(actions[0].method, "POST"); assert_eq!(actions[0].href, "/compute/rqtl"); assert_eq!(actions[1].href, "/compute/gemma"); let rqtl = actions[0].body.as_ref().unwrap(); assert_eq!(rqtl["trait_name"], "mytrait"); assert_eq!(rqtl["samples"][0]["name"], "BXD1"); assert_eq!(rqtl["samples"][0]["value"], 9.5); assert_eq!(rqtl["samples"][1]["value"], serde_json::Value::Null); let gemma = actions[1].body.as_ref().unwrap(); assert_eq!(gemma["trait_values"], serde_json::json!([9.5, null])); // The paths are placeholders, deliberately: the server does not // know where a genotype file it may read lives. assert!(gemma["genotype_file"].as_str().unwrap().starts_with('<')); assert!(rqtl["genotype_file"].as_str().unwrap().starts_with('<')); } #[test] fn a_group_suggestion_needs_no_paths_at_all() { let actions = mapping_actions_for_group(&samples(), "BXD::10001", Some("BXD")); for action in &actions { let body = action.body.as_ref().unwrap().to_string(); assert!(!body.contains('<'), "no placeholders when the group is known: {body}"); assert_eq!(action.body.as_ref().unwrap()["group"], "BXD"); } assert_eq!(actions[1].body.as_ref().unwrap()["samples"][0]["name"], "BXD1"); } #[test] fn the_description_says_what_must_be_replaced() { let actions = mapping_actions(&samples(), "mytrait"); for action in &actions { assert!( action.description.to_lowercase().contains("replace"), "{}", action.description ); assert!(action.description.contains("2 values"), "{}", action.description); } } } /// Add a normalisation pipeline's fields to a suggested body, leaving it /// byte-identical when there is nothing to add -- a caller who fetched /// normalized values must map the same numbers, so the suggestion carries /// the pipeline rather than silently mapping the raw ones. fn with_normalization( body: serde_json::Value, normalization: Option<&crate::normalize::Pipeline>, ) -> serde_json::Value { let Some(pipeline) = normalization else { return body; }; let mut object = match body { serde_json::Value::Object(object) => object, other => return other, }; for (key, value) in pipeline.to_json() { object.insert(key, value); } serde_json::Value::Object(object) } // --------------------------------------------------------------------------- // `next` links: where a caller can go from what it just got. // // `next` is for `GET`s only (following one must return 200), which is why the // compute endpoints' `POST`s live in `actions`. The rule these builders // follow is that a link is offered whenever the id it needs is already known // to the server: a version's frequencies and markers, a marker's location and // tally, a group's traits and PheWAS, a trait's values, a species' datasets. // Offering the obvious next call is cheaper than making every client // re-derive the path vocabulary, and it is the only way an agent discovers // that `/groups/unlisted/...` exists at all. // --------------------------------------------------------------------------- use crate::response::path_segment; /// `(href, description)`, ready for [`NextAction`]. pub type Link = (String, &'static str); /// Path-safe identifier. fn seg(value: &str) -> String { path_segment(value) } /// The listings every endpoint can reach, so a dead end is never returned. pub fn root_links() -> Vec { vec![ ("/groups".to_string(), "Every group, with its species and mapping method"), ("/species".to_string(), "Every species"), ( "/mapping-methods".to_string(), "The mapping tools GeneNetwork has run (R/qtl, GEMMA, qtlreaper, ...)", ), ("/openapi.json".to_string(), "This API's OpenAPI document"), ] } /// Everything one genotype version offers: the tally, the names, the /// positions, and the scans that run on it. pub fn genotype_version_links(group: &str, version: &str) -> Vec { let base = format!( "/groups/{}/genotypes/{}", seg(group), seg(version) ); vec![ ( format!("{base}/frequencies"), "What this panel is actually called as: call -> frequency", ), ( format!("{base}/markers"), "The marker names this version carries, paged (positions are one call per marker)", ), ( format!("{base}/markers/{{marker}}/location"), "One marker's position (name, chr, cM, Mb) -- fill in a marker name", ), ( format!("{base}/markers/{{marker}}/frequencies"), "One marker's calls across the panel -- a flat LOD from a nearly-missing marker \ looks like real data otherwise", ), ( format!("{base}/markers/{{marker}}/classes?trait={{trait_id}}"), "One marker's trait values summarised per genotype class -- how a peak that rests \ on two animals is told apart from one that rests on a hundred", ), ( format!("/groups/{}", seg(group)), "The group's record (species, mapping method, trait count)", ), ] } /// The same, for a file no group lists. pub fn unlisted_genotype_links(name: &str) -> Vec { let base = format!("/groups/unlisted/genotypes/{}", seg(name)); vec![ ( format!("{base}/frequencies"), "What this panel is actually called as: call -> frequency", ), ( format!("{base}/markers"), "The marker names it carries, paged", ), ( format!("{base}/markers/{{marker}}/location"), "One marker's position -- fill in a marker name", ), ( format!("{base}/markers/{{marker}}/frequencies"), "One marker's calls across the panel -- fill in a marker name", ), ] } /// One marker of one version: its position, its tally, and its PheWAS. pub fn marker_links(group: &str, version: &str, marker: &str) -> Vec { let base = format!( "/groups/{}/genotypes/{}/markers", seg(group), seg(version) ); vec![ ( format!("{base}/{}/location", seg(marker)), "This marker's position (name, chr, cM, Mb)", ), ( format!("{base}/{}/frequencies", seg(marker)), "This marker's calls across the panel, as frequencies", ), (base, "The names of every marker in this version"), ( format!( "/groups/{}/genotypes/{}/frequencies", seg(group), seg(version) ), "The whole panel's call frequencies", ), ( format!("/groups/{}/phewas?locus={}", seg(group), seg(marker)), "PheWAS: every published trait of this group peaking at this marker", ), ] } /// One marker of a file no group lists. pub fn unlisted_marker_links(name: &str, marker: &str) -> Vec { let base = format!("/groups/unlisted/genotypes/{}/markers", seg(name)); vec![ ( format!("{base}/{}/location", seg(marker)), "This marker's position (name, chr, cM, Mb)", ), ( format!("{base}/{}/frequencies", seg(marker)), "This marker's calls across the panel, as frequencies", ), (base, "Every marker name in this file"), ( format!("/groups/unlisted/genotypes/{}/frequencies", seg(name)), "The whole file's call frequencies", ), ] } /// The forward hint every scan should carry: how many animals sit in each /// genotype class at the peak. A peak resting on two animals and one resting /// on a hundred read the same in a LOD column, and only this call tells them /// apart. `{trait_id}` is the caller's to fill in -- the scan knows the trait's /// values, not its PublishXRef.Id. pub fn class_hint(group: &str, version: &str, marker: &str) -> Link { ( format!( "/groups/{}/genotypes/{}/markers/{}/classes?trait={{trait_id}}", seg(group), seg(version), seg(marker) ), "Count the animals in each genotype class at this peak (n, mean, sd, min, max per \ class): a class of one or two is a different claim from a hundred. Fill in the trait id", ) } /// What a group leads to. pub fn group_links(group: &str) -> Vec { let base = format!("/groups/{}", seg(group)); vec![ ( format!("{base}/genotypes"), "The genotype versions this group can be mapped with, newest first", ), ( format!("{base}/traits"), "Every published trait of this group", ), ( "/species".to_string(), "The species of this group, among every species the deployment holds", ), ( // A shape rather than an address: the caller substitutes a file // name. tests/envelope.rs skips hrefs with braces and insists the // description says what to put there, so keep that sentence. "/groups/unlisted/genotypes/{name}/frequencies".to_string(), "Or tally a genotype file that no group lists; substitute the file name (without \ its .geno) for {name}", ), ] } /// What one trait leads to. pub fn trait_links(group: &str, trait_id: i64) -> Vec { let base = format!("/groups/{}/traits/{}", seg(group), trait_id); vec![ ( format!("{base}/values"), "This trait's value per strain (and the mapping suggestions they come with)", ), ( format!("/groups/{}/genotypes", seg(group)), "The genotype versions this group's traits can be mapped against", ), ( format!("/groups/{}/traits", seg(group)), "Every published trait of this group", ), ] } /// The marker name of the row with the highest value in `score_column` -- /// what a scan's strongest locus is, for a PheWAS link that can be followed. pub fn peak_marker_of(rows: &serde_json::Value, name_column: usize, score_column: usize) -> Option { rows.as_array()? .iter() .filter_map(|row| { let row = row.as_array()?; let score = row.get(score_column)?.as_f64()?; let name = row.get(name_column)?.as_str()?.to_string(); Some((name, score)) }) .max_by(|left, right| left.1.partial_cmp(&right.1).unwrap_or(std::cmp::Ordering::Equal)) .map(|(name, _)| name) }