about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-09 14:01:00 +0000
committerPjotr <wrk@bosa.lan>2026-11-09 14:01:00 +0000
commita698c48ee204cd68efc479b01132ae9c037213bb (patch)
tree9af621bc16457d1ea99ddb4ffa7a28588e5316a7 /docs
parent195ee5d285da98bc911813d8e578f4f17e9ba7ba (diff)
downloadgenenetwork4-a698c48ee204cd68efc479b01132ae9c037213bb.tar.gz
covariates: refuse a mostly-numeric attribute, and teach the skill to use them
Fitting `SeqCvge` as a covariate came back as `502 gemma_failed` with a
message about LU decomposition: its values are depths (`40`, `41`) with a
few two-library entries (`36+39L`), so the attribute was coded as **twenty
categories** and GEMMA died on the resulting dummies. The failure named
GEMMA, which is the wrong place to look.

`code_case_attribute` now refuses that shape at the covariate step, naming
the values and what to send instead:

  422 invalid_covariate: case attribute 'SeqCvge': the attribute mixes
  numbers with number-like text (14 of 19 values look numeric, but e.g.
  '36+30L' does not), so coding it as categories would fit a quantity as a
  factor -- and GEMMA fails on the result. Pass an explicit `map` giving
  each of those a number (there are 5 such value(s): ...), or send the
  numbers inline.

The rule is deliberately narrow: an odd level with *no* digits (`1, 2,
unknown`) is still a level and still coded, so nothing that worked stops
working; only dirty numbers are caught.

Also, the skill's covariate coverage -- which the review above found thin:

* when a covariate is worth trying (metadata that could confound: sex, age,
  epoch, batch, sequencing depth), and the covariate step in the session
  outline;
* read `.data.descriptions` before choosing one -- they are the only place
  that says `SeqCvge` is sequencing depth and `Epoch` a family subgroup --
  and the endpoint table now says so;
* read the covariate line in `notes` for the coding and the complete-case
  n, and report that n beside any LOD/p change; plus `Cyro`/`Cryo` being
  two levels in BXD;
* the categorical-vs-numeric rule measured rather than asserted: `RRID`
  refused (82 distinct), `Status`/`Epoch` accepted, and the compound-value
  trap written up with the `map` workaround;
* GEMMA's dummy columns, the column it drops when a level has no fitted
  individual, and that R/qtl's note has no such line; missing values
  dropping individuals; the 8-covariate cap and the `group` requirement.

* src/covariates.rs: the refusal, with a unit test for both sides of it;
* tests/gemma.rs: `SeqCvge` is a 422 naming `map`, not a GEMMA failure;
* docs/www/SKILL.md: the covariate section, the session line, and the
  case-attributes rows in the endpoint table.

300 tests pass; the same four as before do not.
Diffstat (limited to 'docs')
-rw-r--r--docs/www/SKILL.md57
1 files changed, 50 insertions, 7 deletions
diff --git a/docs/www/SKILL.md b/docs/www/SKILL.md
index 79f9971..401772f 100644
--- a/docs/www/SKILL.md
+++ b/docs/www/SKILL.md
@@ -25,7 +25,10 @@ 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. After each step, suggest the next one.
+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.
 
 ## 0. Do this first
 
@@ -163,10 +166,49 @@ 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: [{"case_attribute": "<name>"}]` uses a case attribute of the
-    group; get the valid names from `/groups/{g}/case-attributes` (`.data.names`;
-    BXD has `Epoch, RRID, SeqCvge, Status`, **not** Sex, and an unknown name is
-    `422 covariate_unavailable` listing the valid ones).
+  * **Covariates** (both engines): `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
+    stronger result. **Read `.data.descriptions` before choosing one**, not
+    just `.data.names`: the names do not explain themselves, and the
+    descriptions do (BXD: `SeqCvge` = "Depth of DNA sequencing for 1 male of
+    each strain in 2016", `Epoch` = BXD family subgroups, `Epoch1(BXD1-32)`,
+    `Epoch2-6 (BXD33-220)`, `Status` = `Live= Available at JAX,
+    Cryo=Cryopreserved only, Extinct`, `RRID` = a SciCrunch identifier).
+    BXD has no `Sex`; an unknown name is `422 covariate_unavailable` listing
+    the ones the group does have.
+    * **Then read the covariate line in `notes`.** It reports the coding and
+      the complete cases, e.g. `Covariate Status (Live=…, Cryo=…): categorical
+      coded Cryo=0, Cyro=1, Ext=2, Live=3, UTHSC=4, UTHSC2=5, 90 of 93
+      samples have a value, 34 with both the trait and the covariate; 6
+      levels`. Report that *n* next to any LOD/p change — a peak that shifts
+      because 60 samples left the fit is not a discovery. Note the data's own
+      typo: `Cyro` and `Cryo` are two levels.
+    * **Categorical vs numeric.** Numeric text passes through as numbers;
+      anything else with 2–20 distinct values among *the strains being
+      mapped* is coded 0..k−1 in sorted order; more than 20, a single level,
+      or a `map` that misses a value is a `422` asking for an explicit `map`.
+      Measured on BXD (trait 10001, `BXD.4`): `RRID` is refused — `422 …
+      82 distinct values, too many to code automatically` — while `Status`
+      (6 levels) and `Epoch` are accepted.
+    * **Compound values are a trap.** `SeqCvge` mixes numbers with two-library
+      values (`40+31L`) and carries 30 distinct values across the group: if
+      few enough fall inside the mapped panel it is accepted, but as a
+      *categorical* — and the GEMMA run then fails (`502 gemma_failed`) rather
+      than telling you why. The same is true of any mostly-numeric attribute
+      with a few odd entries. Send the coding yourself:
+      `{"case_attribute": "SeqCvge", "map": {"40+31L": 71, "40": 40, …}}`, or
+      inline `{"name": …, "kind": "numerical", "values": […]}`.
+    * **GEMMA** gets k−1 dummy columns (first level = reference) and *drops*
+      a level none of the fitted individuals carries; the reply says so
+      (`GEMMA fits 4 covariate column(s): Status.Ext, …` and `Covariate
+      column(s) left out because they do not vary …`). R/qtl takes the single
+      level column and dummy-expands it itself, so its note has no such line.
+    * Missing covariate values drop those individuals from the fit (both
+      engines), which `notes` reports as `Missing covariate values: …`.
+    * At most 8 covariates, and they need a `group` (the individuals are
+      aligned by name, which a bare `genotype_file` request does not carry).
   * `genotype_version`: list them with `/groups/{g}/genotypes` (BXD.8 is current).
 * Timings seen: R/qtl about 7 s (1 MB reply), GEMMA about 3 s (1.9 MB), plots
   instant. They are synchronous; `?id=` only adds progress logging.
@@ -194,9 +236,10 @@ real answer.
 | path | gives you |
 |---|---|
 | `/species`, `/species/{s}`, `/species/{s}/datasets` | species, expression datasets |
-| `/groups?species=`, `/groups/{g}`, `/groups/{g}/strains`, `/groups/{g}/datasets`, `/groups/{g}/case-attributes` | populations and samples |
+| `/groups?species=`, `/groups/{g}`, `/groups/{g}/strains`, `/groups/{g}/datasets` | populations and samples |
+| `/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 |
+| `/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 |
 | `/datasets/{ds}[/probesets[/{p}[/values]]]`, `/traits/{ds}[/{t}[/values]]` | expression data |
 | `/publications/{pubmed_id}/traits` | traits a paper reports (PubMed id, not `publication_id`) |