diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-07 17:35:44 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-07 17:35:44 +0000 |
| commit | 632cf0c61ee4602ee8423593a8aa8fd8a4373c41 (patch) | |
| tree | ee81f60e0211f510969ac8122ac496048c5db87d /docs | |
| parent | 555fe06b0ab72240f254206f0f0c4ddf76ec00c5 (diff) | |
| download | genenetwork4-632cf0c61ee4602ee8423593a8aa8fd8a4373c41.tar.gz | |
phewas: every trait peaking within a window of one position
PublishXRef records the marker each published trait's QTL peaks at
(Locus) with its LRS, which is a PheWAS waiting to happen: fix a
position, find the markers within a window of it, and ask which traits
peak at those markers.
GET /groups/{group}/phewas?locus=rs30524230&window=10000
GET /groups/{group}/phewas?chr=9&mb=29.940961&window=10000
The window is in base pairs, centred, default 10 kb either side -- the
"10K up and downstream" case. Positions come from the group's genotype
marker table (the endpoint added last round), so `genotype_version`
selects whose markers define the window and the answer reports them
alongside the traits: an empty `traits` list is then readable as
"nothing peaks that close" rather than a failure, and a ten-times wider
window is offered as `next`.
Measured on real data, ±10 kb around rs30524230 (chr 9, 29.94 Mb, a BXD
QTL peak at LRS 460): 4 markers, 10 traits, from LOD 99.9 down to 2.68 --
ANPEP_band, then microbiome/haematology/infectious-disease traits. That
cluster of 99.9s is the 460 LRS cap, not a spectrum, which the notes say.
* src/db.rs (get_phewas_traits): PublishXRef rows for a set of peak
markers, joining Phenotype/Publication through the existing
trait_info_sql, strongest first; marker names are re-validated before
they reach the IN list.
* src/routes/phewas.rs: the endpoint, token-gated; window/centre
validation (422 for none or negative), 404 for an unknown locus, notes
for the empty cases, and a unit test for the version/group helper.
* tests/phewas.rs: markers in the window, traits sorted by LRS with
lod = lrs/4.604, every hit peaking at a listed marker, zero-width window,
the two failure modes, and that the suggested wider window resolves.
* README.md, docs/www/ai-instruction.md (new 4b: how to read a PheWAS),
docs/www/operator-checklist.md: the endpoint and its reading.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/www/ai-instruction.md | 34 | ||||
| -rw-r--r-- | docs/www/operator-checklist.md | 9 |
2 files changed, 43 insertions, 0 deletions
diff --git a/docs/www/ai-instruction.md b/docs/www/ai-instruction.md index b1b2586..e6c4d0b 100644 --- a/docs/www/ai-instruction.md +++ b/docs/www/ai-instruction.md @@ -361,6 +361,40 @@ names in `meta.columns` (`chr`, `rs`, `ps`, … for GEMMA; `name`, `chr`, would dominate. `notes` carries the exact command line that ran, which is the fastest way to see what your request turned into. +## 4b. PheWAS: what else peaks near this QTL + +Given a QTL peak — from a mapping above, or any trait's `locus` — ask +what else peaks there: + +```sh +curl -s -H "$AUTH" "$API/groups/BXD/phewas?locus=rs30524230&window=10000" +curl -s -H "$AUTH" "$API/groups/BXD/phewas?chr=9&mb=29.940961&window=10000" +``` + +The window is in **base pairs, centred on the position**: `window=10000` +is 10 kb up- and downstream (that is the default). `genotype_version` +picks whose marker table defines the window; leave it out for the +current one. + +The answer lists the `markers` the window covered and the `traits` whose +peak marker is one of them, strongest first, each with `trait_id`, +`dataset`, `abbreviation`, `description`, its peak `locus`/`chr`/`mb`, +`lrs`, `lod`, `mean`, `additive`, `nsamples`, `pubmed_id` and a `url`. + +Read it like this: + +* `traits: []` with markers present means nothing publishes a peak that + close — it is an answer, not an error. Widen `window` (the response's + `next` suggests a ten-times wider one) — marker spacing, not the API, + decides what fits in 10 kb; +* `markers: []` means the genotype version has no marker there at all; +* a peak marker is one common locus: several traits sharing it may be + the same underlying locus measured several ways, or a pleiotropic + effect — the descriptions tell you which; +* `lod = lrs / 4.604`, and the highest `lrs` in GeneNetwork is capped at + 460 (LOD 99.9), so a tight cluster at that value is the cap, not a + spectrum. + ## 5. Errors and what to do Errors are RFC 7807-style JSON (`type`, `title`, `status`, `code`, diff --git a/docs/www/operator-checklist.md b/docs/www/operator-checklist.md index 22ec6ef..5cd203f 100644 --- a/docs/www/operator-checklist.md +++ b/docs/www/operator-checklist.md @@ -195,6 +195,15 @@ is CPU-bound on the box, so rate-limit per token or keep the audience small — `limit_req` in the config is one way, but it keys on address, not token. +## PheWAS + +`GET /groups/{group}/phewas` reads `PublishXRef` only -- the peak marker, +LRS and the join to `Phenotype`/`Publication` -- plus the group's +genotype marker table for positions. It is token-only like the other +metadata routes, and it inherits the exposure question below: +`PublishXRef` covers published traits, whose datasets are the `*Publish` +freezes. + ## Data exposure * Public rule: `public > 0 && confidentiality < 1`, or older than five |
