about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr Prins <pjotr.public01@thebird.nl>2026-11-14 14:03:14 +0000
committerPjotr Prins <pjotr.public01@thebird.nl>2026-11-14 14:03:14 +0000
commitc822ba22ce00c1615bf47fc8a13f28590aba424a (patch)
treeba8d5f2a9517b14c93f30ef93a9cc170b07880f5 /docs
parentdc40e89ce72b3213d227a1ee90df701aa17a1c7f (diff)
downloadgenenetwork4-c822ba22ce00c1615bf47fc8a13f28590aba424a.tar.gz
skills: ravanan is the default GEMMA runner, gemma-wrapper is the reference
docs/www/SKILL.md: the workflow example now calls /compute/gemma/ravanan,
and a new "Which GEMMA endpoint" section says when not to: Slurm down or
submission failing, the user asks, a field ravanan refuses (covariates,
normalization), or verifying results -- where the wrapper endpoint is the
reference and scripts/gemma-compare.py is the check.

docs/dev/SKILL.md: the same rule from the developer side, in Testing --
verify mapping changes by sending one body to both endpoints and never
'fix' a difference by switching endpoints, plus the reminder that the
wrapper's cache only hits from 5eb53fa on, so a stale gemma-wrapper on
PATH looks like a broken cache.
Diffstat (limited to 'docs')
-rw-r--r--docs/dev/SKILL.md14
-rw-r--r--docs/www/SKILL.md31
2 files changed, 43 insertions, 2 deletions
diff --git a/docs/dev/SKILL.md b/docs/dev/SKILL.md
index ce936d7..0ba66dd 100644
--- a/docs/dev/SKILL.md
+++ b/docs/dev/SKILL.md
@@ -243,6 +243,20 @@ Use `utoipa` + `utoipa-axum`, not a hand-maintained spec file:
 
 ## Testing
 
+- **GEMMA mapping: ravanan is the default runner, `/compute/gemma` is the
+  reference.** Any change that touches mapping is verified by sending the same
+  request body to both endpoints -- `scripts/gemma-compare.py --base URL --body
+  FILE` prints both wall-clock times and exits non-zero if a row disagrees on
+  `rs`, `beta`, `se`, `l_mle` or `p_lrt`. The wrapper endpoint is only the
+  fallback when Slurm is unavailable, so never "fix" a mapping difference by
+  switching endpoints: the difference is the finding.
+- Both are content-cached (ravanan's store; gemma-wrapper's `--cache-dir`), so a
+  repeat of an identical request is ~1-2 s against ~12-15 s cold -- cheap enough
+  to re-run for verification. Note the wrapper's cache only hits from
+  gemma-wrapper `5eb53fa` on (archives without the per-run `.log.txt` can never
+  satisfy its cache-hit check); check `gemma-wrapper --help | head -1` for the
+  version before concluding a cache is broken.
+
 Two parallel suites exercising the same endpoints:
 
 - Rust integration tests (`tests/*.rs`) call the router in-process via
diff --git a/docs/www/SKILL.md b/docs/www/SKILL.md
index 8cd2ee9..b6864c1 100644
--- a/docs/www/SKILL.md
+++ b/docs/www/SKILL.md
@@ -135,10 +135,11 @@ curl -s -H "$AUTH" -H 'Content-Type: application/json' --data @$D/body.json \
 curl -s -H "$AUTH" -H 'Content-Type: application/json' --data @$D/rqtl.json \
   -D $D/h.txt -o rqtl.svg "$API/plot/rqtl?trait=BXD::20010"; grep -i x-plot-summary $D/h.txt
 
-# GEMMA: same shape
+# GEMMA: same shape. Use /compute/gemma/ravanan -- it is the default runner
+# (see "Which GEMMA endpoint" below).
 jq '.actions[]|select(.href|endswith("/compute/gemma"))|.body' $D/v.json > $D/gbody.json
 curl -s -H "$AUTH" -H 'Content-Type: application/json' --data @$D/gbody.json \
-  "$API/compute/gemma?id=t20010" > $D/gemma.json
+  "$API/compute/gemma/ravanan?id=t20010" > $D/gemma.json
 curl -s -H "$AUTH" -H 'Content-Type: application/json' --data @$D/gemma.json \
   -o gemma.svg "$API/plot/gemma?trait=BXD::20010"
 
@@ -151,6 +152,32 @@ curl -s -H "$AUTH" --get --data-urlencode locus=<peak marker> --data window=1000
 Give the user the SVGs (they render directly) and quote the `x-plot-summary`
 header (peak, and the reference lines drawn when you asked for them).
 
+### Which GEMMA endpoint: ravanan by default
+
+Two endpoints run the same computation, and the reply shape is identical:
+
+| endpoint | runs |
+|---|---|
+| `/compute/gemma/ravanan` | `gemma` itself, one invocation per chromosome, scattered by ravanan (Slurm) |
+| `/compute/gemma` | `gemma-wrapper` (kinship, then GWA, both `--loco`) as a server subprocess, no cluster |
+
+**Use `/compute/gemma/ravanan` by default.** Reach for `/compute/gemma` only
+when:
+
+- **Slurm is down or job submission fails** (`502`/`ravanan_failed`, or a job
+  that never leaves `PENDING`) -- the in-process runner needs no cluster;
+- **the user asks for it**, or the request needs something only it supports
+  (covariates, normalization -- ravanan refuses those with a `422`);
+- **you are testing or verifying results.** The wrapper endpoint is the
+  reference: send the same body to both and compare rows. `scripts/gemma-compare.py
+  --base URL --body FILE` does exactly that, prints both wall-clock times, and
+  exits non-zero if any `rs` disagrees on `beta`, `se`, `l_mle` or `p_lrt`.
+
+Both are warm-cached and both are cheap to repeat: a repeat of an identical
+request comes back from cache (ravanan's store, or gemma-wrapper's
+`--cache-dir`) in ~1-2 s against ~12-15 s for a first run, so re-running to
+verify costs almost nothing.
+
 ## 3. GeneNetwork functionality, in detail
 
 **Mapping and plots (POST, verified working)**