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. --- README.md | 27 ++-- docs/genotypes.md | 15 +++ docs/www/ai-instruction.md | 12 +- src/genotypes.rs | 114 ++++++++++++++++ src/lib.rs | 2 + src/routes/genotypes.rs | 330 ++++++++++++++++++++++++++++++++++++++++++++- tests/genotypes.rs | 10 +- 7 files changed, 493 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 9c33cb1..a134131 100644 --- a/README.md +++ b/README.md @@ -315,16 +315,27 @@ Details, including example responses, below. ``` - `GET /groups/{group}/genotypes` - the genotype files this group can be - mapped with, newest first: each `version` (e.g. `BXD.8`), the panel's - `title`, `individuals`, `markers`, whether `gemma` and `rqtl` can run on - it, and which one is `current` (what a mapping request gets by - default). Files and paths stay server-side -- this names versions, not - locations -- and `POST /compute/rqtl` / `/compute/gemma` take `group` - plus an optional `genotype_version` instead of paths. The order comes - from the deployment's `genotype/.json`, whose `genofile` list is + mapped with, newest first: each `version` (e.g. `BXD.8`), the `file` + name (`BXD.8.geno`), the panel's `title`, `individuals`, `markers`, + whether `gemma` and `rqtl` can run on it, and which one is `current` + (what a mapping request gets by default). The order comes from the + deployment's `genotype/.json`, whose `genofile` list is newest-first, the same rule GeneNetwork2 uses; groups with no JSON (HET3-ITP) fall back to the highest version number and the listing's - `notes` says so. See [docs/genotypes.md](docs/genotypes.md). + `notes` says so. `POST /compute/rqtl` / `/compute/gemma` take `group` + plus an optional `genotype_version` instead of paths. + + `GET /groups/{group}/genotypes/{version}` is the metadata of one of + them: the file name, the header's own `@`-labels (`type`, `mat`, + `pat`, ...), the panel's `individuals` in file order and the `strains` + a mapping actually uses (parents/F1s dropped), `num_individuals`, + `num_strains`, `markers`, and per-chromosome marker counts. + `GET /groups/{group}/genotypes/{version}/markers?page=&limit=&chr=` is + the marker table -- name, chromosome, cM, Mb -- paged, positional rows + like `/compute/gemma`'s. So a caller can see the panel, the markers and + the header it is mapping against; the **genotype calls themselves are + never served**, only summaries of them. See + [docs/genotypes.md](docs/genotypes.md). - `GET /groups/{group}/traits` - returns every published (phenotype) trait belonging to a group, the listing equivalent of 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 diff --git a/src/genotypes.rs b/src/genotypes.rs index 0079581..335fceb 100644 --- a/src/genotypes.rs +++ b/src/genotypes.rs @@ -61,6 +61,9 @@ impl std::fmt::Display for GenotypeError { pub struct GenotypeFile { /// The stem, e.g. "BXD.8" -- what a mapping request names. pub version: String, + /// The genotype file's name, e.g. "BXD.8.geno". A name, not a path: + /// enough to say what ran, not where the deployment keeps it. + pub file: String, /// The JSON's `title`, when it has one, e.g. "WGS-based (Mar2022)". pub title: Option, /// Individuals in the file's header. @@ -195,6 +198,7 @@ pub fn list(dir: &Path, group: &str) -> Result, GenotypeError> (0, 0) }; files.push(GenotypeFile { + file: format!("{stem}.geno"), version: stem, title, individuals, @@ -353,6 +357,87 @@ pub fn non_strains(dir: &Path, group: &str, panel: &[String]) -> BTreeSet, + pub mb: Option, +} + +/// Everything a `.geno` header and marker table say, and nothing it does +/// not: the `@key:value` labels, the panel's individual names in file +/// order, and one entry per marker. +#[derive(Debug)] +pub struct FileMeta { + /// The `@`-labels (`name`, `type`, `mat`, `pat`, `het`, `unk`, + /// `scale`), in file order. + pub labels: Vec<(String, String)>, + /// Individuals, in the file's column order. + pub individuals: Vec, + /// Markers, in file order. + pub markers: Vec, +} + +/// Read a `.geno`'s metadata: labels, individuals, marker positions. The +/// genotype calls themselves are read and discarded, never returned. +pub fn file_meta(geno: &Path) -> Result { + let text = std::fs::read_to_string(geno).map_err(|e| io_err(geno, e))?; + let mut labels = Vec::new(); + let mut individuals = Vec::new(); + let mut markers = Vec::new(); + let mut header_seen = false; + let mut start = 3; + for line in text.lines() { + let line = line.trim_end_matches('\r'); + if line.trim().is_empty() || line.starts_with('#') { + continue; + } + if let Some(rest) = line.strip_prefix('@') { + if let Some((key, value)) = rest.split_once(':') { + labels.push((key.trim().to_string(), value.trim().to_string())); + } + continue; + } + let columns: Vec<&str> = line.split('\t').collect(); + if !header_seen { + header_seen = true; + start = if columns.len() > 3 && columns[3] == "Mb" { + 4 + } else { + 3 + }; + individuals = columns[start.min(columns.len())..] + .iter() + .map(|name| name.trim().to_string()) + .collect(); + continue; + } + let number = |index: usize| -> Option { + columns.get(index).and_then(|value| value.trim().parse().ok()) + }; + markers.push(Marker { + chr: columns.first().copied().unwrap_or("").trim().to_string(), + name: columns.get(1).copied().unwrap_or("").trim().to_string(), + cm: number(2), + mb: number(3).or_else(|| number(2)), + }); + } + if !header_seen { + return Err(GenotypeError::NotFound(format!( + "{}: no header line", + geno.display() + ))); + } + Ok(FileMeta { + labels, + individuals, + markers, + }) +} + /// A genotype file set as one engine needs it, plus a note on what it is. pub struct Prepared { pub genotype_file: PathBuf, @@ -599,6 +684,35 @@ mod tests { assert_eq!(marker_count(&dir.join("genotype/T.1.geno")).unwrap(), 2); } + #[test] + fn file_meta_reads_labels_individuals_and_marker_positions() { + let dir = scratch("meta"); + fs::write( + dir.join("genotype/R.1.geno"), + "# a comment\n@name:R\n@type:riset\n@mat:B\n@pat:D\n\ + Chr\tLocus\tcM\tMb\tS1\tS2\n\ + 1\trs1\t1.5\t3.0\tB\tD\n\ + 2\trs2\t2.5\t5.0\tD\tB\n", + ) + .unwrap(); + let meta = file_meta(&dir.join("genotype/R.1.geno")).unwrap(); + assert_eq!( + meta.labels, + vec![ + ("name".to_string(), "R".to_string()), + ("type".to_string(), "riset".to_string()), + ("mat".to_string(), "B".to_string()), + ("pat".to_string(), "D".to_string()), + ] + ); + assert_eq!(meta.individuals, vec!["S1", "S2"]); + assert_eq!(meta.markers.len(), 2); + assert_eq!(meta.markers[1].name, "rs2"); + assert_eq!(meta.markers[1].chr, "2"); + assert_eq!(meta.markers[1].cm, Some(2.5)); + assert_eq!(meta.markers[1].mb, Some(5.0)); + } + #[test] fn the_json_order_decides_which_version_is_current() { let dir = scratch("json"); diff --git a/src/lib.rs b/src/lib.rs index 22462fc..3c027bd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -85,6 +85,8 @@ pub fn app() -> Router { .routes(routes!(routes::search::search)) .routes(routes!(routes::correlation::correlation)) .routes(routes!(routes::genotypes::group_genotypes)) + .routes(routes!(routes::genotypes::group_genotype_version)) + .routes(routes!(routes::genotypes::group_genotype_markers)) .routes(routes!(routes::gemma::compute_gemma)) .routes(routes!(routes::gemma::compute_gemma_ravanan)) .routes(routes!(routes::gemma::gemma_status)) diff --git a/src/routes/genotypes.rs b/src/routes/genotypes.rs index d90d73c..7f632bd 100644 --- a/src/routes/genotypes.rs +++ b/src/routes/genotypes.rs @@ -9,10 +9,12 @@ //! those server-side from the group and version. use axum::Json; -use axum::extract::Path; -use serde::Serialize; +use axum::extract::{Path, Query}; +use serde::{Deserialize, Serialize}; use utoipa::ToSchema; +use gnauth_macros::gnauth; + use crate::auth::AuthToken; use crate::config::Config; use crate::error::{ApiError, Unauthorized}; @@ -25,6 +27,8 @@ pub struct GenotypeVersion { /// What a mapping request names in `genotype_version`, e.g. "BXD.8". /// `null` in `current` means "whatever `genotype_version` is now". pub version: String, + /// The genotype file's name, e.g. "BXD.8.geno". + pub file: String, /// The panel's own title for it, e.g. "WGS-based (Mar2022)". #[serde(skip_serializing_if = "Option::is_none")] pub title: Option, @@ -48,6 +52,71 @@ pub struct GroupGenotypes { pub versions: Vec, } +/// One marker's position. +#[derive(Serialize, ToSchema)] +pub struct MarkerInfo { + pub name: String, + pub chr: String, + #[serde(skip_serializing_if = "Option::is_none")] + pub cm: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub mb: Option, +} + +/// Everything about one genotype version except the genotypes. +#[derive(Serialize, ToSchema)] +pub struct GenotypeDetail { + pub group: String, + pub version: String, + /// The genotype file's name, e.g. "BXD.8.geno". + pub file: String, + #[serde(skip_serializing_if = "Option::is_none")] + pub title: Option, + /// The panel's own `@`-labels (`type`, `mat`, `pat`, `het`, `unk`, + /// `scale`, ...), as key/value pairs in file order. + pub labels: Vec