about summary refs log tree commit diff
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-10 18:49:09 +0000
committerPjotr <wrk@bosa.lan>2026-11-10 18:49:09 +0000
commitfc99de3a5e8dfe2f54ac7e34e7422672baaa97bc (patch)
tree48d75b7ece7f67bbc22b623aa7e02ed6128411af
parentd614b073351773fa5b698a3c8a4374191e9341b9 (diff)
downloadgenenetwork4-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.md6
-rw-r--r--docs/www/SKILL.md4
-rw-r--r--src/routes/fitqtl.rs9
-rw-r--r--src/routes/gemma.rs6
-rw-r--r--src/routes/qtl2.rs16
-rw-r--r--src/routes/rqtl.rs6
-rw-r--r--src/suggest.rs23
-rw-r--r--tests/links.rs71
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 &notes {
         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]
+    );
+}