diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-10 18:49:09 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-10 18:49:09 +0000 |
| commit | fc99de3a5e8dfe2f54ac7e34e7422672baaa97bc (patch) | |
| tree | 48d75b7ece7f67bbc22b623aa7e02ed6128411af | |
| parent | d614b073351773fa5b698a3c8a4374191e9341b9 (diff) | |
| download | genenetwork4-fc99de3a5e8dfe2f54ac7e34e7422672baaa97bc.tar.gz | |
api: scans point at the class counts behind their own peak
The gotcha notes in SKILL.md tell an agent to count the animals per
genotype class before believing a peak; a note in a document is only
found by whoever reads it, so the replies now say it too, at the peak
they just computed.
* suggest::class_hint builds
/groups/{g}/genotypes/{v}/markers/{peak}/classes?trait={trait_id} --
a real GET with one placeholder, because a scan knows the trait's
values, not its PublishXRef.Id.
* /compute/{rqtl,gemma,qtl2,fitqtl} add it to `next` after the PheWAS
link, naming the peak each reply found and the version the request
named (a {version} placeholder when it named none).
* The genotype subtree carries the template too: a version's detail,
and a concrete marker's own links.
* /compute/qtl2 gains the sentence that explains the divergence: on a
riself (riset) panel heterozygous calls are dropped before the scan
(R/qtl's convert2riself) and the HMM re-imputes them, while GEMMA
keeps them at dosage 0.5, so a mostly-H marker cannot peak there and
two engines can name different markers of one region without either
being wrong.
tests/links.rs: a scan's reply offers the class counts at its own peak --
the link names the version and the peak marker the reply reports, and
leaves {trait_id} for the caller.
| -rw-r--r-- | README.md | 6 | ||||
| -rw-r--r-- | docs/www/SKILL.md | 4 | ||||
| -rw-r--r-- | src/routes/fitqtl.rs | 9 | ||||
| -rw-r--r-- | src/routes/gemma.rs | 6 | ||||
| -rw-r--r-- | src/routes/qtl2.rs | 16 | ||||
| -rw-r--r-- | src/routes/rqtl.rs | 6 | ||||
| -rw-r--r-- | src/suggest.rs | 23 | ||||
| -rw-r--r-- | tests/links.rs | 71 |
8 files changed, 141 insertions, 0 deletions
diff --git a/README.md b/README.md index db9fd0e..96360ed 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,12 @@ to the PheWAS at it; a trait leads to its values, its genotypes and its group; `/version` leads to the listings. A caller that knows only `/version` can walk to anything. +A scan is the case that matters most: its reply points at the *class counts* +behind its own peak (`.../markers/{peak}/classes?trait={trait_id}`), because +"LOD 2.93" reads the same whether it rests on two animals or a hundred, and +`/compute/qtl2` says in `notes` that a `riself` panel drops heterozygous calls +before the scan while GEMMA keeps them at dosage 0.5. + `next` is a promise that following a link is a `GET` that returns 200, which is what makes blind following safe. So a link that would need a parameter the server cannot fill is *not* offered (`/groups/{g}/phewas` without a locus is a diff --git a/docs/www/SKILL.md b/docs/www/SKILL.md index 2688f24..0f0638c 100644 --- a/docs/www/SKILL.md +++ b/docs/www/SKILL.md @@ -197,6 +197,10 @@ header (peak and, for GEMMA, the Bonferroni line). flat LOD as real data. Probability-valued files are binned 0.05 wide (`?bin=` to change); a file over 256 MB is refused (413) rather than read. +* Compute replies carry the class-count hint at their own peak + (`.../markers/{peak}/classes?trait={trait_id}`): filling in the trait id is + how you check a peak before reporting it, and `/compute/qtl2`'s `notes` + explains what a `riself` conversion did to `H`. * Follow `next` freely: every link is a `GET` that returns 200, and the API offers the whole graph from any response (genotypes -> frequencies -> markers -> a marker's location/tally -> PheWAS; trait -> values -> diff --git a/src/routes/fitqtl.rs b/src/routes/fitqtl.rs index 8c0c283..d37e4be 100644 --- a/src/routes/fitqtl.rs +++ b/src/routes/fitqtl.rs @@ -429,6 +429,15 @@ pub async fn compute_fitqtl( "PheWAS: every published trait peaking at this fit's strongest marker", ); } + let version = request + .genotype_version + .clone() + .unwrap_or_else(|| "{version}".to_string()); + if let Some(peak) = &peak_marker { + let (href, description) = + crate::suggest::class_hint(&group, &version, peak); + envelope = envelope.with_next(&href, description); + } envelope = envelope.with_links(crate::suggest::group_links(&group)); } Ok(Json(envelope)) diff --git a/src/routes/gemma.rs b/src/routes/gemma.rs index 2062425..cc7eb44 100644 --- a/src/routes/gemma.rs +++ b/src/routes/gemma.rs @@ -580,6 +580,12 @@ pub async fn compute_gemma( ), "PheWAS: every published trait peaking within 10 kb of this GWAS's peak", ); + let version = request + .genotype_version + .clone() + .unwrap_or_else(|| "{version}".to_string()); + let (href, description) = crate::suggest::class_hint(group, &version, &peak); + envelope = envelope.with_next(&href, description); envelope = envelope.with_links(crate::suggest::group_links(group)); } } diff --git a/src/routes/qtl2.rs b/src/routes/qtl2.rs index 6cc736c..45aa4b5 100644 --- a/src/routes/qtl2.rs +++ b/src/routes/qtl2.rs @@ -566,6 +566,13 @@ pub async fn compute_qtl2( if !output.summary.trim().is_empty() { envelope = envelope.with_note(&format!("qtl2: {}", output.summary.trim())); } + envelope = envelope.with_note( + "On a riself (riset) panel heterozygous calls are dropped before the scan -- R/qtl's \ + convert2riself -- and the HMM re-imputes them from flanking markers; GEMMA keeps them \ + as dosage 0.5. A marker that is mostly H therefore cannot produce a peak here, and two \ + engines can name different markers of one region without either being wrong. The \ + classes link in `next` shows the per-class counts.", + ); for note in ¬es { envelope = envelope.with_note(note); } @@ -589,6 +596,15 @@ pub async fn compute_qtl2( "PheWAS: every published trait peaking at this scan's strongest marker", ); } + let version = request + .genotype_version + .clone() + .unwrap_or_else(|| "{version}".to_string()); + if let Some(peak) = &peak_marker { + let (href, description) = + crate::suggest::class_hint(&group, &version, peak); + envelope = envelope.with_next(&href, description); + } envelope = envelope.with_links(crate::suggest::group_links(&group)); } Ok(Json(envelope)) diff --git a/src/routes/rqtl.rs b/src/routes/rqtl.rs index 0e142fb..8ff265e 100644 --- a/src/routes/rqtl.rs +++ b/src/routes/rqtl.rs @@ -448,6 +448,12 @@ pub async fn compute_rqtl( ), "PheWAS: every published trait peaking within 10 kb of this QTL's peak", ); + let version = request + .genotype_version + .clone() + .unwrap_or_else(|| "{version}".to_string()); + let (href, description) = crate::suggest::class_hint(group, &version, &peak); + envelope = envelope.with_next(&href, description); envelope = envelope.with_links(crate::suggest::group_links(group)); } } diff --git a/src/suggest.rs b/src/suggest.rs index 51d729a..9dad0b1 100644 --- a/src/suggest.rs +++ b/src/suggest.rs @@ -323,6 +323,11 @@ pub fn genotype_version_links(group: &str, version: &str) -> Vec<Link> { 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)", ), @@ -404,6 +409,24 @@ pub fn unlisted_marker_links(name: &str, marker: &str) -> Vec<Link> { ] } +/// 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<Link> { let base = format!("/groups/{}", seg(group)); diff --git a/tests/links.rs b/tests/links.rs index 498181a..3c2c01b 100644 --- a/tests/links.rs +++ b/tests/links.rs @@ -155,3 +155,74 @@ async fn a_marker_leads_to_its_tally_and_its_phewas() { "a marker leads to the PheWAS at it: {links:?}" ); } + +/// A scan's reply carries the forward hint that reads the peak for what it +/// is: how many animals sit in each genotype class there. Without it, "LOD +/// 2.93" is the same sentence whether it rests on two animals or a hundred. +#[tokio::test] +async fn a_scan_points_at_the_class_counts_behind_its_peak() { + let Some(token) = common::auth_token().await else { + eprintln!("skipping a_scan_points_at_the_class_counts_behind_its_peak: no token"); + return; + }; + if !common::db_available() { + eprintln!("skipping a_scan_points_at_the_class_counts_behind_its_peak: no database"); + return; + } + let response = common::get_with_token( + "GET /groups/BXD/traits/10001/values", + "/groups/BXD/traits/10001/values", + &token, + ) + .await; + assert_eq!(response.status(), StatusCode::OK); + let bytes = response.into_body().collect().await.unwrap().to_bytes(); + let samples: Value = common::data(&bytes); + let body = serde_json::json!({ + "group": "BXD", + "genotype_version": "BXD.4", + "trait_name": "BXD::10001", + "samples": samples, + }); + let response = + common::post_json_with_token("POST /compute/rqtl", "/compute/rqtl", &token, &body).await; + assert_eq!(response.status(), StatusCode::OK); + let bytes = response.into_body().collect().await.unwrap().to_bytes(); + let envelope: Value = serde_json::from_slice(&bytes).unwrap(); + let links: Vec<&str> = envelope["next"] + .as_array() + .unwrap() + .iter() + .map(|action| action["href"].as_str().unwrap()) + .collect(); + let hint = links + .iter() + .find(|href| href.contains("/classes?trait=")) + .unwrap_or_else(|| panic!("a scan offers the class counts at its peak: {links:?}")); + assert!( + hint.starts_with("/groups/BXD/genotypes/BXD.4/markers/"), + "the hint names this scan's own version and marker: {hint}" + ); + assert!( + hint.contains("{trait_id}"), + "the trait id is the caller's to fill in: {hint}" + ); + // And the marker it names is the peak the reply reported. + // /compute/rqtl's rows live under data.markers. + let rows = envelope["data"]["markers"].as_array().unwrap(); + let peak = rows + .iter() + .max_by(|left, right| { + left[3] + .as_f64() + .unwrap() + .partial_cmp(&right[3].as_f64().unwrap()) + .unwrap() + }) + .unwrap(); + assert!( + hint.contains(peak[0].as_str().unwrap()), + "the hint is at the peak marker {}: {hint}", + peak[0] + ); +} |
