about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-10-13 13:52:15 +0000
committerPjotr <wrk@bosa.lan>2026-10-13 13:52:15 +0000
commitb3c43a2bb0cb7f1e5d0c0a3d08f76f82d9ef881f (patch)
tree307740ad66ecf80783c8790931725644d4795bec /docs
parent2551418eede25d0ffaebef67f9950f13e3551567 (diff)
downloadgenenetwork4-b3c43a2bb0cb7f1e5d0c0a3d08f76f82d9ef881f.tar.gz
docs: align and width-cap markdown tables
Realigns every pipe-table column to a uniform width, and trims cell
text so each table stays under 100 chars per row, moving one
over-long cell's detail (InbredSet.MappingMethodId) into a footnote
paragraph below its table instead of dropping it. The gn-auth.md
endpoints table is left over 100 chars, with a note explaining why: its
longest path is 66 chars by itself, leaving no room for the other two
columns under that cap.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/genenetwork_datatypes.md120
-rw-r--r--docs/gn-auth.md5
2 files changed, 71 insertions, 54 deletions
diff --git a/docs/genenetwork_datatypes.md b/docs/genenetwork_datatypes.md
index 0189ba2..fbf8882 100644
--- a/docs/genenetwork_datatypes.md
+++ b/docs/genenetwork_datatypes.md
@@ -19,18 +19,18 @@ Field semantics, from `topics/gn-uploader/adding-species.gmi` (written
 while manually adding C. elegans to the database) and cross-checked
 against the live schema:
 
-| Field           | Meaning                                                                                                                                                                           |
-|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `Id`            | Internal GeneNetwork species identifier (auto-increment primary key).                                                                                                             |
-| `SpeciesId`     | Set equal to `Id` after insert (see "Known quirks" below); other tables' `SpeciesId` foreign keys reference this, not `Id` directly, though in practice the two are always equal. |
-| `SpeciesName`   | A layman's name, e.g. "Mouse", "Roundworm", "Barley".                                                                                                                             |
-| `Name`          | Mostly the same as `SpeciesName`, lowercased, e.g. "mouse". This is the short name used in URLs and API lookups.                                                                  |
-| `MenuName`      | Display name shown in the UI, typically combining `SpeciesName` and `FullName`/assembly, e.g. "Mouse (Mus musculus, mm10)".                                                       |
-| `FullName`      | The species' binomial (scientific) name, e.g. "Mus musculus", "Caenorhabditis elegans".                                                                                           |
-| `Family`        | A loose grouping across species, e.g. "Vertebrates", "Nematodes".                                                                                                                 |
-| `FamilyOrderId` | Sort order within `Family` for menu display. Exact derivation undocumented (`adding-species.gmi` flags this with a TODO).                                                         |
-| `TaxonomyId`    | The NCBI Taxonomy ID (https://www.ncbi.nlm.nih.gov/), e.g. 10090 for mouse, 6239 for C. elegans.                                                                                  |
-| `OrderId`       | Sort order for display. Exact derivation undocumented, same TODO as `FamilyOrderId`.                                                                                              |
+| Field           | Meaning                                                                    |
+|-----------------|-----------------------------------------------------------------------------|
+| `Id`            | Internal species identifier (auto-increment primary key).                  |
+| `SpeciesId`     | Set equal to `Id` after insert; FKs use this, not `Id` (see Known quirks). |
+| `SpeciesName`   | A layman's name, e.g. "Mouse", "Roundworm", "Barley".                      |
+| `Name`          | Lowercased short name for URLs/API, e.g. "mouse".                          |
+| `MenuName`      | UI display name, e.g. "Mouse (Mus musculus, mm10)".                        |
+| `FullName`      | Binomial (scientific) name, e.g. "Mus musculus".                           |
+| `Family`        | A loose grouping across species, e.g. "Vertebrates", "Nematodes".          |
+| `FamilyOrderId` | Sort order within `Family`; derivation undocumented (TODO).                |
+| `TaxonomyId`    | NCBI Taxonomy ID, e.g. 10090 (mouse), 6239 (C. elegans).                   |
+| `OrderId`       | Sort order for display; same undocumented TODO as above.                   |
 
 ### Relationships
 
@@ -135,22 +135,34 @@ populations -- so "RISet" is a slight misnomer for the general case).
 
 ### Fields
 
-| Field             | Meaning                                                                                                                                                                                                                                                   |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `Id`              | Internal GeneNetwork group identifier (auto-increment primary key).                                                                                                                                                                                       |
-| `InbredSetId`     | Set equal to `Id` after insert, same pattern as `Species.SpeciesId`; other tables' `InbredSetId` foreign keys (e.g. `PublishFreeze`, `GenoFreeze`, `ProbeFreeze`) reference this.                                                                         |
-| `InbredSetName`   | Display name shown in the UI -- GN2's `/api/v_pre1/groups` calls this field `DisplayName` in its JSON response -- e.g. "BXD".                                                                                                                             |
-| `Name`            | Short name used in URLs and API lookups, e.g. "BXD", "B6D2F2". Usually the same as `InbredSetName`.                                                                                                                                                       |
-| `SpeciesId`       | FK to `Species.SpeciesId`; every group belongs to exactly one species (see Species section above).                                                                                                                                                        |
-| `FullName`        | Longer descriptive name, e.g. "BXD RI Family", "BXD Family".                                                                                                                                                                                              |
-| `public`          | Numeric visibility/access level (values 0-2 seen in example data); exact threshold semantics not found documented in these repos.                                                                                                                         |
-| `MappingMethodId` | Key into the `MappingMethod` table (`Id`, `Name`): 1 `qtlreaper`, 2 `Rqtl`, 3 `HappyR`, 4 `PLINK`, 5 `FastMap`; null means no mapping tool is offered. This is the authoritative reading, and the one genenetwork4 uses (`mapping_method` is the table's name for the id; `GET /mapping-methods` lists the table). Queried live: 58 groups use 1, 20 use 2, 2 use 3, 22 have none; PLINK and FastMap are defined but unused. GeneNetwork2's `get_mapping_methods` (`gn2/base/data_set/datasetgroup.py`) instead treats the id as a code for a set of tools ("1" = GEMMA + QTLReaper + R/qtl, "2" = GEMMA only, ...); that reading is superseded and is not followed here. |
-| `GeneticType`     | The breeding scheme, e.g. "riset" (recombinant inbred strains, as in BXD) or "intercross" (e.g. F2/AIL populations).                                                                                                                                      |
-| `Family`          | Loose grouping across groups, parallel to `Species.Family`.                                                                                                                                                                                               |
-| `FamilyOrder`     | Sort order within `Family` for menu display (note: unlike `Species.FamilyOrderId`, this column has no `Id` suffix).                                                                                                                                       |
-| `MenuOrderId`     | Sort order for display in the group menu.                                                                                                                                                                                                                 |
-| `InbredSetCode`   | Short code, e.g. "BXD", "AXB", "AKD" -- seen used as a prefix/identifier in precompute tooling and genotype file naming (`topics/systems/mariadb/precompute-mapping-input-data.gmi`).                                                                     |
-| `Description`     | Free-text description of the group.                                                                                                                                                                                                                       |
+| Field             | Meaning                                                                   |
+|-------------------|---------------------------------------------------------------------------|
+| `Id`              | Internal group identifier (auto-increment primary key).                   |
+| `InbredSetId`     | Set equal to `Id` after insert; FKs (Publish/Geno/ProbeFreeze) use this.  |
+| `InbredSetName`   | UI display name -- GN2 calls this `DisplayName` in JSON -- e.g. "BXD".    |
+| `Name`            | Short name for URLs/API, e.g. "BXD", "B6D2F2"; usually = `InbredSetName`. |
+| `SpeciesId`       | FK to `Species.SpeciesId`; a group belongs to exactly one species.        |
+| `FullName`        | Longer descriptive name, e.g. "BXD RI Family", "BXD Family".              |
+| `public`          | Numeric visibility level (0-2 seen); threshold semantics undocumented.    |
+| `MappingMethodId` | Mapping tool offered, if any; see footnote below the table.               |
+| `GeneticType`     | Breeding scheme, e.g. "riset" (as in BXD) or "intercross" (F2/AIL).       |
+| `Family`          | Loose grouping across groups, parallel to `Species.Family`.               |
+| `FamilyOrder`     | Sort order within `Family` (no `Id` suffix, unlike `Species`).            |
+| `MenuOrderId`     | Sort order for display in the group menu.                                 |
+| `InbredSetCode`   | Short code, e.g. "BXD", "AXB"; used in precompute/genotype naming.        |
+| `Description`     | Free-text description of the group.                                       |
+
+`MappingMethodId` is a key into the `MappingMethod` table (`Id`,
+`Name`): 1 `qtlreaper`, 2 `Rqtl`, 3 `HappyR`, 4 `PLINK`, 5 `FastMap`;
+null means no mapping tool is offered. This is the authoritative
+reading, and the one genenetwork4 uses (`mapping_method` is the
+table's name for the id; `GET /mapping-methods` lists the table).
+Queried live: 58 groups use 1, 20 use 2, 2 use 3, 22 have none; PLINK
+and FastMap are defined but unused. GeneNetwork2's
+`get_mapping_methods` (`gn2/base/data_set/datasetgroup.py`) instead
+treats the id as a code for a set of tools ("1" = GEMMA + QTLReaper +
+R/qtl, "2" = GEMMA only, ...); that reading is superseded and is not
+followed here.
 
 ### Relationships
 
@@ -219,20 +231,20 @@ and surfacing its `Phenotype`/`Publication` metadata alongside them.
 
 ### Fields
 
-| Field           | Meaning                                                                                                                |
-|-----------------|------------------------------------------------------------------------------------------------------------------------|
-| `Id`            | Trait identifier within a group; unique only paired with `InbredSetId`, not on its own (see Known quirks).             |
-| `InbredSetId`   | FK to `InbredSet`; every trait belongs to exactly one group.                                                           |
-| `PhenotypeId`   | FK to `Phenotype`, the trait's description and units.                                                                  |
-| `PublicationId` | FK to `Publication`, the article the trait was published in.                                                           |
-| `DataId`        | FK to `PublishData.Id`, the trait's actual per-strain values.                                                          |
-| `mean`          | Mean value across strains, for the trait's single stored QTL hit.                                                      |
-| `Locus`         | Marker/SNP name of that stored hit.                                                                                    |
-| `LRS`           | LOD/LRS score of that hit.                                                                                             |
-| `additive`      | Additive effect size of that hit.                                                                                      |
-| `Sequence`      | Disambiguates multiple `PublishXRef` rows that would otherwise collide on `(InbredSetId, PhenotypeId, PublicationId)`. |
-| `comments`      | Free-text comment on the mapping.                                                                                      |
-| `NSamples`      | Number of strains/samples the trait was computed over.                                                                 |
+| Field           | Meaning                                                                        |
+|-----------------|--------------------------------------------------------------------------------|
+| `Id`            | Trait id within a group; unique only paired with `InbredSetId` (Known quirks). |
+| `InbredSetId`   | FK to `InbredSet`; every trait belongs to exactly one group.                   |
+| `PhenotypeId`   | FK to `Phenotype`, the trait's description and units.                          |
+| `PublicationId` | FK to `Publication`, the article the trait was published in.                   |
+| `DataId`        | FK to `PublishData.Id`, the trait's actual per-strain values.                  |
+| `mean`          | Mean value across strains, for the trait's single stored QTL hit.              |
+| `Locus`         | Marker/SNP name of that stored hit.                                            |
+| `LRS`           | LOD/LRS score of that hit.                                                     |
+| `additive`      | Additive effect size of that hit.                                              |
+| `Sequence`      | Disambiguates rows colliding on `(InbredSetId, PhenotypeId, PublicationId)`.   |
+| `comments`      | Free-text comment on the mapping.                                              |
+| `NSamples`      | Number of strains/samples the trait was computed over.                         |
 
 ### Relationships
 
@@ -298,18 +310,18 @@ key is `DataId`, and the natural key identifying one row is the pair
 
 ### Fields
 
-| Field              | Meaning                                                                                  |
-|--------------------|------------------------------------------------------------------------------------------|
-| `ProbeSetFreezeId` | FK to `ProbeSetFreeze`; identifies the expression dataset this row's mapping belongs to. |
-| `ProbeSetId`       | FK to `ProbeSet`; the probe/gene this row's mapping belongs to.                          |
-| `DataId`           | Primary key; FK to `ProbeSetData.Id`, the trait's actual per-strain values.              |
-| `mean`             | Mean expression value across strains.                                                    |
-| `se`               | Standard error of the mean.                                                              |
-| `Locus`            | Marker/SNP name of this trait's single stored QTL hit.                                   |
-| `LRS`              | LOD/LRS score of that hit.                                                               |
-| `pValue`           | p-value of that hit.                                                                     |
-| `additive`         | Additive effect size of that hit.                                                        |
-| `h2`               | Heritability estimate.                                                                   |
+| Field              | Meaning                                                             |
+|--------------------|---------------------------------------------------------------------|
+| `ProbeSetFreezeId` | FK to `ProbeSetFreeze`; the expression dataset this row belongs to. |
+| `ProbeSetId`       | FK to `ProbeSet`; the probe/gene this row's mapping belongs to.     |
+| `DataId`           | Primary key; FK to `ProbeSetData.Id`, the per-strain values.        |
+| `mean`             | Mean expression value across strains.                               |
+| `se`               | Standard error of the mean.                                         |
+| `Locus`            | Marker/SNP name of this trait's single stored QTL hit.              |
+| `LRS`              | LOD/LRS score of that hit.                                          |
+| `pValue`           | p-value of that hit.                                                |
+| `additive`         | Additive effect size of that hit.                                   |
+| `h2`               | Heritability estimate.                                              |
 
 ### Relationships
 
diff --git a/docs/gn-auth.md b/docs/gn-auth.md
index 2802784..87d0c70 100644
--- a/docs/gn-auth.md
+++ b/docs/gn-auth.md
@@ -140,6 +140,11 @@ user-specific answer. That's by design, not a bug to route around.
 
 ## Endpoints reference
 
+This table runs wider than 100 chars: its longest path,
+`/auth/resource/populations/resource-id/<speciesid>/<inbredsetid>`, is
+66 chars by itself, leaving no room for the Auth required/Purpose
+columns if kept under that width.
+
 | Method | Path                                                               | Auth required                                        | Purpose                                                                                          |
 |--------|--------------------------------------------------------------------|------------------------------------------------------|--------------------------------------------------------------------------------------------------|
 | GET    | `/auth/public-jwks`                                                | none                                                 | RSA public keys for verifying JWTs locally.                                                      |