diff options
| author | Pjotr Prins <pjotr.public01@thebird.nl> | 2026-11-14 14:03:14 +0000 |
|---|---|---|
| committer | Pjotr Prins <pjotr.public01@thebird.nl> | 2026-11-14 14:03:14 +0000 |
| commit | c822ba22ce00c1615bf47fc8a13f28590aba424a (patch) | |
| tree | ba8d5f2a9517b14c93f30ef93a9cc170b07880f5 /docs | |
| parent | dc40e89ce72b3213d227a1ee90df701aa17a1c7f (diff) | |
| download | genenetwork4-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.md | 14 | ||||
| -rw-r--r-- | docs/www/SKILL.md | 31 |
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)** |
