From fc99de3a5e8dfe2f54ac7e34e7422672baaa97bc Mon Sep 17 00:00:00 2001 From: Pjotr Date: Tue, 10 Nov 2026 18:49:09 +0000 Subject: 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. --- src/routes/fitqtl.rs | 9 +++++++++ src/routes/gemma.rs | 6 ++++++ src/routes/qtl2.rs | 16 ++++++++++++++++ src/routes/rqtl.rs | 6 ++++++ src/suggest.rs | 23 +++++++++++++++++++++++ 5 files changed, 60 insertions(+) (limited to 'src') 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 @@ -322,6 +322,11 @@ pub fn genotype_version_links(group: &str, version: &str) -> Vec { "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)", @@ -404,6 +409,24 @@ pub fn unlisted_marker_links(name: &str, marker: &str) -> Vec { ] } +/// 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)); -- cgit 1.4.1