about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-07 20:03:44 +0000
committerPjotr <wrk@bosa.lan>2026-11-07 20:03:44 +0000
commit61e6767404c72fd8a70c2f905f29a40bbba1f023 (patch)
treef46960ab5c9dd6838290d31ce89c714e8aeedb77 /docs
parentc087e4186874921f48caefa2d8630f5bf05b3c0d (diff)
downloadgenenetwork4-61e6767404c72fd8a70c2f905f29a40bbba1f023.tar.gz
ai-instruction: a section on case attributes
The §3 table had one line for /groups/{group}/case-attributes and nothing
else, so an assistant could find the endpoint and still not use it: the
response shape, the fact that the values are free text (`"Sex": "F"`,
`"Status": "Live"`), that `strain` is the group's mapping unit rather
than always a strain line, that which attributes exist is a property of
the study (BXD has no Sex; BXD-Longevity and eight other BXD-family
studies do), and that a published trait is the easier source when the
study has one.

Written around the worked case we settled on: AgeAtDeath in
BXD-Longevity, sex per animal available as a case attribute or as trait
10010 (1.0/0.0), and why that covariate matters there -- it varies
within the panel and has its own QTL (LRS 76 at rs13481466).

* docs/www/ai-instruction.md (3. What you can read): "Case attributes",
ahead of Search, matching the table's order.
Diffstat (limited to 'docs')
-rw-r--r--docs/www/ai-instruction.md50
1 files changed, 50 insertions, 0 deletions
diff --git a/docs/www/ai-instruction.md b/docs/www/ai-instruction.md
index 6735506..f4b2b61 100644
--- a/docs/www/ai-instruction.md
+++ b/docs/www/ai-instruction.md
@@ -177,6 +177,56 @@ Paths are relative to `https://vesuvio.pu.ac.ke/gn4`.
 | `/mapping-methods` | QTL methods offered |
 | `/search?q={query}` | Xapian full-text search over published phenotypes |
 
+### Case attributes
+
+Every group carries the metadata its studies recorded alongside the
+phenotypes — sex, age, tissue, batch, colony, diet — and
+`/groups/{group}/case-attributes` returns all of it:
+
+```sh
+curl -s -H "$AUTH" "$API/groups/BXD-Longevity/case-attributes"
+```
+
+```json
+{
+  "data": {
+    "names": ["Age", "B.Wt.", "Colony", "Diet…", "Sex", "Status", "Strain", "Tx"],
+    "values": [
+      {"strain": "F3092", "case_attributes": {"Sex": "F", "Age": "…", "Tx": "…"}},
+      {"strain": "F3093", "case_attributes": {"Sex": "F", …}}
+    ]
+  }
+}
+```
+
+Four things to know before using it:
+
+* **`strain` is the group's mapping unit**, not necessarily a strain
+  line: in `BXD-Longevity` these are individual animals (`F3092`…), in
+  `BXD` they are lines (`BXD1`…). Those are the same names
+  `/groups/{group}/traits/{id}/values` uses, which is what lets an
+  attribute be aligned onto a trait.
+* **The values are free text**, not numbers: `"Sex": "F"`, `"Status":
+  "Live"`, `"SeqCvge": "36+39L"`, and some are empty. Converting one into
+  something numeric (a covariate, a filter, a grouping) is your job —
+  `F → 1, M → 0`, anything unrecognised → missing.
+* **Which attributes exist is a property of the study.** `BXD` has
+  `Epoch, RRID, SeqCvge, Status` and **no Sex**; `BXD-Longevity`,
+  `BXD-NIA-AD`, `BXD-Micturition`, `BXD-MBD-UTHSC`, `BXD-UTHSC-PC`,
+  `BXD-JAX-OFS`, `BXD-Heart-Metals`, `B6D2RI` and others do have Sex.
+  Ask the endpoint rather than assuming.
+* **If the study publishes the attribute as a trait, prefer the trait** —
+  it is already numeric and keyed the same way. `BXD-Longevity` publishes
+  `Sex` as trait `10010` (`1.0`/`0.0` over the same 3281 animals), so
+  `/groups/BXD-Longevity/traits/10010/values` is the easier source than
+  parsing `"F"`/`"M"`.
+
+A worked case: `AgeAtDeath` in `BXD-Longevity` (trait `10001`, 3281
+animals) has every sample's sex available both ways, which is exactly the
+kind of covariate a mapping wants — sex varies *within* the panel rather
+than describing the strain lines, and it has its own QTL here (LRS 76 at
+`rs13481466`), which is why leaving it out changes what the scan finds.
+
 ### Search
 
 `/search` is served by a **Xapian** index, queried with Xapian's own