diff options
| author | Pjotr <wrk@bosa.lan> | 2026-10-13 13:52:15 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-10-13 13:52:15 +0000 |
| commit | b3c43a2bb0cb7f1e5d0c0a3d08f76f82d9ef881f (patch) | |
| tree | 307740ad66ecf80783c8790931725644d4795bec /docs | |
| parent | 2551418eede25d0ffaebef67f9950f13e3551567 (diff) | |
| download | genenetwork4-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.md | 120 | ||||
| -rw-r--r-- | docs/gn-auth.md | 5 |
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. | |
