From 18d18b1c125c06dd67dcf54ccbd89eb128643737 Mon Sep 17 00:00:00 2001 From: Pjotr Date: Sat, 7 Nov 2026 17:10:28 +0000 Subject: genotypes: expose the metadata, never the genotype calls The listing named versions but not files; a caller could pick one and still not see what was in it. Three token-gated routes now describe a version completely, short of the matrix: GET /groups/{group}/genotypes versions, files, sizes, current GET /groups/{group}/genotypes/{version} file name, header labels, individuals, strains, chromosomes GET /groups/{group}/genotypes/{version}/markers markers (name, chr, cM, Mb), paged The detail reads the file's own `@`-labels (type, mat, pat, het, unk, scale) and its panel in column order, and reports both the whole panel and the strains a mapping uses after the parents/F1s rule -- so a caller can check a request before sending it and interpret a result after. Markers come back as positional rows with `meta.columns`, paged with `?page`/`?limit` and filterable with `?chr`, following /compute/gemma's shape rather than inventing one. The genotype calls stay on the server: file_meta() reads the matrix to skip it, and nothing returns a cell. * src/genotypes.rs (Marker, FileMeta, file_meta; GenotypeFile::file): header labels, individuals and marker positions; unit test. * src/routes/genotypes.rs: the two new handlers, token-gated like the listing, plus `file` in the listing and counts in the detail. * tests/genotypes.rs: the listing carries file names but no paths. * README.md, docs/genotypes.md, docs/www/ai-instruction.md: what the three routes give, and that the matrix is not among them. --- docs/genotypes.md | 15 +++++++++++++++ docs/www/ai-instruction.md | 12 ++++++++++-- 2 files changed, 25 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/genotypes.md b/docs/genotypes.md index 4835865..55f7a6d 100644 --- a/docs/genotypes.md +++ b/docs/genotypes.md @@ -101,6 +101,21 @@ and were posted to the API. | BXD, `BXD.8.geno` | R/qtl scanone | 10001 | 235 | 34 | 7.5 s | 21 056 markers | | HET3-ITP, `HET3-ITP.12.geno` (Apr 2023) | R/qtl scanone | 10000 lifespan | 6 447 | 6 438 | 83.1 s | 893 markers, peak LOD 7.95 at `1_24042124` (chr 1, 24.04 Mb) | +## What the API tells a caller about a genotype file + +Three routes, all behind the bearer token like every other endpoint: + +| route | what it gives | +|---|---| +| `GET /groups/{group}/genotypes` | versions newest-first, each with its `file` name, title, `individuals`, `markers`, which engines can use it, and which is `current` | +| `GET /groups/{group}/genotypes/{version}` | that file's `file` name, its header `@`-labels, the panel's `individuals` in file order, the `strains` a mapping uses, counts, and per-chromosome marker counts | +| `GET /groups/{group}/genotypes/{version}/markers?page=&limit=&chr=` | the marker table: name, chromosome, cM, Mb — paged, positional rows | + +**The genotype calls are never served.** A caller sees the panel, the +markers and the header, which is what it needs to frame a mapping and to +check one; the matrix itself stays on the server, and the compute +endpoints take a group and a version rather than a path. + ## Reproducing the measurements The measurements above were taken before the API took over the diff --git a/docs/www/ai-instruction.md b/docs/www/ai-instruction.md index effe1c8..bb71a98 100644 --- a/docs/www/ai-instruction.md +++ b/docs/www/ai-instruction.md @@ -275,8 +275,16 @@ That lists each `version` (e.g. `BXD.8`), its `title`, `individuals`, `markers`, whether `gemma` and `rqtl` can run on it, and which one is `current` — what a mapping gets if you name no version. Pass `group` to the mapping and the server resolves the files; add -`"genotype_version": "BXD.4"` for an older panel. Paths are deliberately -not part of the API: you never name, or see, a genotype file. +`"genotype_version": "BXD.4"` for an older panel. + +You do not have to map blind: `GET /groups/{group}/genotypes/{version}` +gives that panel's file name, its header labels (`type`, `mat`, `pat`, +…), the individuals in file order, the strains a mapping actually uses, +and per-chromosome marker counts, and +`GET /groups/{group}/genotypes/{version}/markers?page=&limit=&chr=` gives +the markers themselves (name, chr, cM, Mb). That is enough to frame or +check a mapping. The genotype calls are not served — do not look for +them, and do not try to download a genotype matrix. The values and the genotype file have to describe the **same individuals, in the same order, one for one**: one entry per panel -- cgit 1.4.1