diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-09 14:01:00 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-09 14:01:00 +0000 |
| commit | a698c48ee204cd68efc479b01132ae9c037213bb (patch) | |
| tree | 9af621bc16457d1ea99ddb4ffa7a28588e5316a7 /docs | |
| parent | 195ee5d285da98bc911813d8e578f4f17e9ba7ba (diff) | |
| download | genenetwork4-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.md | 57 |
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`) | |
