about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-11 13:07:03 +0000
committerPjotr <wrk@bosa.lan>2026-11-11 13:07:03 +0000
commitf4d2d719f90774e85bc47eca041bc469f0f0951d (patch)
treeb31f206be9e954cc11de6db5523438e9521e1164 /docs
parentc9db07f6d372b0b8812e5f6698257a9df94dc1ef (diff)
downloadgenenetwork4-f4d2d719f90774e85bc47eca041bc469f0f0951d.tar.gz
gemma: the permutation refusal names both routes, including running GEMMA itself
We do not run GEMMA permutations -- each repeats the whole LOCO scan and the
gate gives GEMMA one slot -- but "not supported here" is not the same as
"not available". The refusal now says both:

  1. POST /compute/bulklmm with nperm: 1000 -- an LMM whose thresholds come
     from rotations that keep the kinship (R/qtl's nperm does not, and is
     anti-conservative on a structured panel);
  2. run GEMMA's own permutation locally. The reply's notes already name the
     bimbam pair and the phenotype file, so `gemma-wrapper --permutate` or
     `gemma -lmm 9 --permutate` on those inputs reproduces exactly the null
     GEMMA would have used -- hours instead of seconds, which is the honest
     price of that particular null.

docs/bulklmm.md gains the table this belongs in: three ways to get a
threshold, ordered by how honest the null is for a structured panel
(rotation with kinship; GEMMA's own LOCO permutation run locally; R/qtl's
nperm as a sanity check only). SKILL.md says the same in two lines.

tests/gemma.rs now asserts both halves of the refusal, and the earlier
assertion on /compute/rqtl -- which stopped being true when the refusal was
rewritten -- is replaced rather than left passing by accident.
Diffstat (limited to 'docs')
-rw-r--r--docs/bulklmm.md14
-rw-r--r--docs/www/SKILL.md5
2 files changed, 19 insertions, 0 deletions
diff --git a/docs/bulklmm.md b/docs/bulklmm.md
index cc6bc73..8a39798 100644
--- a/docs/bulklmm.md
+++ b/docs/bulklmm.md
@@ -14,6 +14,20 @@ things that are easy to get wrong when a result is quoted.
 | `/compute/qtl2` | LMM, LOCO, HMM probabilities | LOCO | no |
 | `/compute/bulklmm` | LMM, **global** kinship | one K for the whole genome | **yes, cheaply**: rotates by K's eigen decomposition |
 
+**Three ways to get a threshold, in order of honesty for a structured panel:**
+
+| where | null | cost |
+|---|---|---|
+| `/compute/bulklmm` with `nperm` | rotations that keep the kinship | seconds |
+| GEMMA's own `--permutate`, **run locally** | GEMMA's exact LOCO null | one full LOCO scan per permutation: hours |
+| R/qtl `nperm` on the same values | phenotypes shuffled across individuals — relatedness destroyed, anti-conservative on RI lines and DO collapses | minutes |
+
+The GEMMA endpoint does not run permutations: each repeats the whole LOCO scan
+and the gate gives GEMMA one slot. Its refusal says both alternatives — and
+names the files it used (the `bimbam/` pair and the phenotype file) so a user who
+wants GEMMA's own null can reproduce it locally, which is the only way to get
+*that* null.
+
 So BulkLMM is the only engine here that can say *"this peak is genome-wide
 significant at α = 0.05"* against a null that respects relatedness. That is what
 `/compute/gemma`'s `permutations_not_supported` refusal now points at.
diff --git a/docs/www/SKILL.md b/docs/www/SKILL.md
index 33cf516..880b569 100644
--- a/docs/www/SKILL.md
+++ b/docs/www/SKILL.md
@@ -171,6 +171,11 @@ header (peak and, for GEMMA, the Bonferroni line).
   depend on relatedness, or when the panel is multiparent; it is slower than
   `/compute/rqtl` (a DO cross costs minutes of genotype probabilities, cached
   per panel). Autosomes only, and `notes` says what was left out.
+* **Need a GEMMA threshold?** This API refuses `nperm` on GEMMA (one LOCO scan
+  per permutation, one GEMMA slot). Two routes: `/compute/bulklmm` with
+  `nperm` (rotation null, seconds), or run GEMMA's own `--permutate` locally on
+  the files the reply names (exact GEMMA null, hours). R/qtl's `nperm` is a
+  sanity check only — its null ignores relatedness.
 * **Need a threshold, not just a LOD?** `POST /compute/bulklmm` (BulkLMM.jl)
   fits an LMM per marker with a global kinship matrix and permutes by rotation,
   so `"nperm": 200` is cheap and its thresholds belong to the model that made the