about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-09 18:30:52 +0000
committerPjotr <wrk@bosa.lan>2026-11-09 18:30:52 +0000
commitadb75296ecd9ef24f4abed0f45a6b8f6dd657d9b (patch)
tree7e415fd6a3d87156bbf253977796478ae16804af /docs
parenteb5320d6f51279acf0b65e5bc9755eec927c93ea (diff)
downloadgenenetwork4-adb75296ecd9ef24f4abed0f45a6b8f6dd657d9b.tar.gz
docs: the skill says fitqtl fits covariates
`/compute/fitqtl` has taken `covariates` since c642f87, and the skill
mentioned it only as a trailing sentence inside the fitqtl bullet -- after
the paragraph that says "both engines", which an assistant skimming for
covariates reads as rqtl-and-gemma. Three changes so the offer is where a
reader looks for it:

* the covariates bullet now names all three endpoints
  (`/compute/rqtl`, `/compute/gemma` **and `/compute/fitqtl`**);
* the fitqtl bullet says it in bold, with why it matters (the `additive` is
  then the effect *after* conditioning), and adds the consequence that the
  LOD no longer matches the scan once a covariate is fitted -- the earlier
  wording claimed parity unconditionally;
* the endpoint table gained `POST /compute/{rqtl,gemma,fitqtl}` (it had no
  entry at all), and the session outline now includes sizing a peak with
  fitqtl when the user asks how much it matters.

Docs only.
Diffstat (limited to 'docs')
-rw-r--r--docs/www/SKILL.md31
1 files changed, 19 insertions, 12 deletions
diff --git a/docs/www/SKILL.md b/docs/www/SKILL.md
index 511d515..858ad12 100644
--- a/docs/www/SKILL.md
+++ b/docs/www/SKILL.md
@@ -25,10 +25,11 @@ next natural option from this list:
 | populations and data | species, groups (BXD...), strains, case attributes, genotype versions, expression datasets and probesets, publications by PubMed id, GN accessions | 4 |
 
 A natural session is: trait, values, R/qtl, plot, GEMMA, plot, PheWAS at the
-peak — and, whenever the group records metadata that could confound the
-trait (sex, age, epoch, batch, sequencing depth), the same mappings again
-with that covariate fitted, to see the peak survive it. After each step,
-suggest the next one.
+peak — and `/compute/fitqtl` at that peak when the user asks how much it
+matters (with a covariate, if one could confound it). Whenever the group
+records metadata that could confound the trait (sex, age, epoch, batch,
+sequencing depth), the same mappings again with that covariate fitted, to see
+the peak survive it. After each step, suggest the next one.
 
 ## 0. Do this first
 
@@ -147,12 +148,16 @@ header (peak and, for GEMMA, the Bonferroni line).
   classes (the same convention GeneNetwork's published additive uses),
   `pct_var` the variance explained, and `p` the model's p-value. At most 100
   markers per call; markers that cannot be fitted are absent, not zero.
-  Its `lod` at a marker matches `/compute/rqtl`'s LOD at that marker, so the
-  two are consistent — quote the scan for "where", this for "how much".
-  Covariates work here too (`covariates: [{"case_attribute": "Sex"}]`, same
-  rules as the scan), and the effect is then the one *after* conditioning;
-  the reply names any covariate column it had to leave out because it does
-  not vary among the phenotyped individuals.
+  **It fits covariates too** — `covariates: [{"case_attribute": "Sex"}]`,
+  the same shape and the same coding as `/compute/rqtl` and
+  `/compute/gemma` — so the `additive` it reports can be the effect *after*
+  conditioning on a confounder, which is usually the number worth quoting.
+  The reply names any covariate column it had to leave out because it does
+  not vary among the phenotyped individuals (R/qtl would otherwise stop
+  with "system is exactly singular"). Without covariates its `lod` at a
+  marker equals `/compute/rqtl`'s LOD at that marker; with one fitted it is
+  a different model, so the two no longer match — quote the scan for
+  "where", this for "how much".
 * `/plot/rqtl`, `/plot/gemma`: post the compute reply back, receive an
   `image/svg+xml` plot. Do not draw your own.
 * Options (all optional, add to the posted body; full list in
@@ -180,7 +185,8 @@ header (peak and, for GEMMA, the Bonferroni line).
     to be the mapped ones. `zscore` is the population sd, matching
     genenetwork.org; effects (`beta`/`additive`) come out on the transformed
     scale, so say which scale you are quoting.
-  * **Covariates** (both engines): `covariates: [{"case_attribute": "<name>"}]`.
+  * **Covariates** (`/compute/rqtl`, `/compute/gemma` **and `/compute/fitqtl`**):
+    `covariates: [{"case_attribute": "<name>"}]`.
     Worth trying when the study's own metadata could confound the trait —
     sex, age at death, batch/epoch, cohort, sequencing depth — because they
     are fitted alongside the marker, and a peak that survives them is the
@@ -254,7 +260,8 @@ real answer.
 | `/groups/{g}/case-attributes` | the group's metadata: `.data.names`, and `.data.descriptions` **saying what each one means** — read those before fitting a covariate |
 | `/groups/{g}/traits`, `/groups/{g}/traits/{id}`, `/groups/{g}/traits/{id}/values` | published traits (the first is the bulk list) |
 | `/groups/{g}/traits/{id}/case-attributes/{attribute}` | a trait's case-attribute values, in the trait's own sample order, plus `description` and a `distinct` count — the honest way to see whether an attribute is usable as a covariate (a constant one is not) |
-| `/groups/{g}/genotypes[/{version}[/markers]]` | genotype versions and markers |
+| `/groups/{g}/genotypes[/{version}[/markers]]` | genotype versions and markers, and the marker names `/compute/fitqtl` takes |
+| `POST /compute/{rqtl,gemma,fitqtl}` | mapping (POST, not a GET): the scan, the LMM, and effect sizes at named markers — all three take `covariates` and `normalize` |
 | `/datasets/{ds}[/probesets[/{p}[/values]]]`, `/traits/{ds}[/{t}[/values]]` | expression data |
 | `/publications/{pubmed_id}/traits` | traits a paper reports (PubMed id, not `publication_id`) |
 | `/accessions/{acc}`, `/mapping-methods` | GN accession lookup, methods offered |