diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-07 20:03:44 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-07 20:03:44 +0000 |
| commit | 61e6767404c72fd8a70c2f905f29a40bbba1f023 (patch) | |
| tree | f46960ab5c9dd6838290d31ce89c714e8aeedb77 /docs | |
| parent | c087e4186874921f48caefa2d8630f5bf05b3c0d (diff) | |
| download | genenetwork4-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.md | 50 |
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 |
