about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-07 17:35:44 +0000
committerPjotr <wrk@bosa.lan>2026-11-07 17:35:44 +0000
commit632cf0c61ee4602ee8423593a8aa8fd8a4373c41 (patch)
treeee81f60e0211f510969ac8122ac496048c5db87d /docs
parent555fe06b0ab72240f254206f0f0c4ddf76ec00c5 (diff)
downloadgenenetwork4-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.md34
-rw-r--r--docs/www/operator-checklist.md9
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