about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-07 16:33:13 +0000
committerPjotr <wrk@bosa.lan>2026-11-07 16:33:26 +0000
commit3babef5d4596d94f3d6d200e4b7bd9815d288b9f (patch)
tree46b955e06966189556dea577846a62e39c689375 /docs
parent14dc58f070c2950c13ae822c4a371cf3d303b16a (diff)
downloadgenenetwork4-3babef5d4596d94f3d6d200e4b7bd9815d288b9f.tar.gz
docs: parents and F1s are excluded by default, measured both ways
Asked whether the BXD mappings ran GN2/GN3's default (no parents, no
F1s): they did not. BXD.8's panel is 198 RI strains + 37 F1s and no
parent columns at all, and the runs passed all 235 with `null` for the
F1s -- phenotypes right, but GEMMA's kinship and R/qtl's cross spanning
235 individuals instead of 198.

Measured on trait 10001, both engines, both panels: identical answers
(GEMMA p 5.9e-07 at rsm10000005700 chr 8, R/qtl LOD 2.9320 at
rs48756159 chr 8), so nothing published from those runs is wrong. The
lesson is that null-filling excludes an individual from the fit but not
from the model; excluding it means subsetting the genotype file.

* docs/genotypes.md: "Parents and F1s are excluded by default" -- the
GN2 (`incparentsf1`) and GN3 (`get_sample_list(inc_par=False,
inc_f1=False)`) mechanisms, what each panel actually holds, the
both-ways measurement, and the rule for the alignment work.
* docs/www/ai-instruction.md (4a), docs/www/operator-checklist.md: the
same, in a sentence and a paragraph respectively.
Diffstat (limited to 'docs')
-rw-r--r--docs/genotypes.md39
-rw-r--r--docs/www/ai-instruction.md5
-rw-r--r--docs/www/operator-checklist.md9
3 files changed, 52 insertions, 1 deletions
diff --git a/docs/genotypes.md b/docs/genotypes.md
index e2d91da..ce829fc 100644
--- a/docs/genotypes.md
+++ b/docs/genotypes.md
@@ -118,6 +118,45 @@ Step 3 is the API's job in the next iteration; until then, a request
 built without it is caught rather than trusted -- R/qtl refuses a count
 mismatch, and GEMMA fails on one.
 
+## Parents and F1s are excluded by default
+
+GeneNetwork2 and GeneNetwork3 map **without** the parents and F1s unless
+asked otherwise: GN2's `DatasetGroup.incparentsf1` defaults to `False`
+(`gn2/base/data_set/datasetgroup.py`) and its `ParInfo` parents are only
+added to the genotype object when it is on; GN3 spells the same thing as
+`get_sample_list(group, inc_par=False, inc_f1=False)`
+(`gn3/db/datasets.py`). The parent/F1 lists themselves come from
+`parents_and_f1s.json` in the data directory.
+
+On this deployment the distinction is narrower than it sounds, because
+the panels already tell you what they hold:
+
+- `BXD.8.geno` is 235 columns = **198 RI strains + 37 F1s**, and **no
+  parent columns at all** (C57BL/6J and DBA/2J are not in the file; the
+  JSON's 235-entry `sample_list` is the same 198+37). So "exclude
+  parents and F1s" here means "use the 198 strains".
+- `HET3-ITP.12.geno` is 6 447 **individual animals** (1 953 `JL…` plus
+  4 494 `UM…`), no parents, no F1s — UM-HET3 maps individuals, so the
+  default is moot.
+
+The first BXD mappings above passed all 235 columns with `null` for the
+F1s (and for every strain the trait does not cover), i.e. the *phenotype*
+set was the trait's 34 strains while the *genotype* side spanned 235. That
+is not GN2's default, and it changes GEMMA's kinship matrix (computed over
+genotypes, not phenotypes) and R/qtl's cross. Measured on trait 10001
+both ways, it happened not to change the answer:
+
+| columns passed | GEMMA best | R/qtl best LOD |
+|---|---|---|
+| all 235 (strains + F1s) | p 5.9e-07 at `rsm10000005700`, chr 8 | 2.9320 at `rs48756159`, chr 8 |
+| 198 strains only | p 5.9e-07 at `rsm10000005700`, chr 8 | 2.9320 at `rs48756159`, chr 8 |
+
+So `null`-filling is enough to keep the *phenotypes* right, but not to
+exclude an individual from the model: the genotype matrix has to be
+subset. When the API takes over the alignment, it should subset to the
+strains by default and offer "include parents and F1s" explicitly, which
+is what GN2's checkbox does.
+
 ## What is still messy
 
 `HET3-ITP` has eleven `.geno` versions on disk (`.2` … `.12`) and **no
diff --git a/docs/www/ai-instruction.md b/docs/www/ai-instruction.md
index e6bdb8c..cfdf117 100644
--- a/docs/www/ai-instruction.md
+++ b/docs/www/ai-instruction.md
@@ -294,7 +294,10 @@ mapping (or for the panel order) rather than guessing — and never use a
 genotype file from a different panel, or a hand-built trait vector. For
 reference, the deployment maps BXD (235 individuals, 34 with values) in
 about 17 s with GEMMA and 8 s with R/qtl, and UM-HET3 lifespan (6 447
-individuals, 893 markers) in about 83 s with R/qtl.
+individuals, 893 markers) in about 83 s with R/qtl. Like GeneNetwork2 and
+GeneNetwork3, a mapping uses the **RI strains only**: parents and F1s are
+excluded by default (BXD's panel is 198 strains + 37 F1s; UM-HET3's is
+individual animals only).
 
 Results are **cached** by input, so running the same request twice costs
 little the second time (a cached GEMMA run on the BXD fixtures comes back
diff --git a/docs/www/operator-checklist.md b/docs/www/operator-checklist.md
index f21337f..6815bd2 100644
--- a/docs/www/operator-checklist.md
+++ b/docs/www/operator-checklist.md
@@ -147,6 +147,15 @@ re-indexing yet, so whoever prepares the request has to. It is the first
 thing to fix: pass the values a caller has, let the server align them
 from the `.geno` header.
 
+Parents and F1s are excluded by default, as in GN2/GN3 (GN2's
+`incparentsf1`, GN3's `get_sample_list(inc_par=False, inc_f1=False)`).
+BXD.8's panel is 198 RI strains + 37 F1s and no parent columns, so that
+default means "the 198 strains"; `HET3-ITP.12` is individual animals
+only. `null`-filling a non-strain individual keeps its phenotype out of
+the fit but *not* its genotype out of GEMMA's kinship matrix or R/qtl's
+cross, so excluding it means subsetting the genotype file — which is what
+the API should do when it takes over the alignment.
+
 Which engines a group offers is `InbredSet.MappingMethodId` (1 → GEMMA,
 QTLReaper, R/qtl; 2 → GEMMA; 3 → R/qtl; 4 → GEMMA, PLINK): BXD = 1,
 HET3-ITP = 3. So UM-HET3 is R/qtl only, correct for a 4-way cross even