diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-07 17:10:28 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-07 17:10:28 +0000 |
| commit | 18d18b1c125c06dd67dcf54ccbd89eb128643737 (patch) | |
| tree | efefbdc30000ff459a46457239bc9fb01035d642 /src | |
| parent | 1f61f8f86443de6353295f7363abbe1c986d863f (diff) | |
| download | genenetwork4-18d18b1c125c06dd67dcf54ccbd89eb128643737.tar.gz | |
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.
Diffstat (limited to 'src')
| -rw-r--r-- | src/genotypes.rs | 114 | ||||
| -rw-r--r-- | src/lib.rs | 2 | ||||
| -rw-r--r-- | src/routes/genotypes.rs | 330 |
3 files changed, 443 insertions, 3 deletions
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<String>, /// Individuals in the file's header. @@ -195,6 +198,7 @@ pub fn list(dir: &Path, group: &str) -> Result<Vec<GenotypeFile>, 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<String excluded } +/// One marker's position, as the `.geno` records it -- the metadata a +/// caller needs to interpret a mapping, without the genotypes themselves. +#[derive(Debug, Clone)] +pub struct Marker { + pub name: String, + pub chr: String, + pub cm: Option<f64>, + pub mb: Option<f64>, +} + +/// 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<String>, + /// Markers, in file order. + pub markers: Vec<Marker>, +} + +/// 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<FileMeta, GenotypeError> { + 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<f64> { + 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, @@ -600,6 +685,35 @@ mod tests { } #[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"); write_geno(&dir, "G.9", &["S1"], 1); 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<String>, @@ -48,6 +52,71 @@ pub struct GroupGenotypes { pub versions: Vec<GenotypeVersion>, } +/// 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<f64>, + #[serde(skip_serializing_if = "Option::is_none")] + pub mb: Option<f64>, +} + +/// 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<String>, + /// The panel's own `@`-labels (`type`, `mat`, `pat`, `het`, `unk`, + /// `scale`, ...), as key/value pairs in file order. + pub labels: Vec<Label>, + /// Individuals in the file, in column order (parents and F1s included). + pub individuals: Vec<String>, + /// `individuals.len()`. + pub num_individuals: usize, + /// The individuals a mapping uses: `individuals` minus the parents and + /// F1s that the default rule drops. + pub strains: Vec<String>, + /// `strains.len()`. + pub num_strains: usize, + /// Markers per chromosome, in the file's order. + pub chromosomes: Vec<Chromosome>, + pub markers: usize, + pub gemma: bool, + pub rqtl: bool, + pub current: bool, +} + +/// One `@key: value` line from the file's header. +#[derive(Serialize, ToSchema)] +pub struct Label { + pub key: String, + pub value: String, +} + +/// A chromosome and how many markers it has. +#[derive(Serialize, ToSchema)] +pub struct Chromosome { + pub name: String, + pub markers: usize, +} + +/// Paging for the marker list. +#[derive(Deserialize, utoipa::IntoParams)] +pub struct MarkerParams { + /// One-based page of `limit` markers. Default 1. + pub page: Option<u32>, + /// Markers per page. Default 100, at most 10000. + pub limit: Option<u32>, + /// Only this chromosome, e.g. "1" or "X". + pub chr: Option<String>, +} + #[utoipa::path(get, path = "/groups/{group}/genotypes", summary = "Genotype files available for a group, newest first", description = "Names each genotype version a group can be mapped with, the panel and \ @@ -62,6 +131,7 @@ request gets by default). Files and paths stay server-side: pass `group` and opt (status = 500, description = "The genotype-files directory could not be read", body = ApiError) ) )] +#[gnauth(token_only)] pub async fn group_genotypes( ctx: Ctx, Path(group): Path<String>, @@ -123,6 +193,7 @@ pub async fn group_genotypes( versions: files .into_iter() .map(|file| GenotypeVersion { + file: file.file, version: file.version, title: file.title, individuals: file.individuals, @@ -161,12 +232,265 @@ pub async fn group_genotypes( )) } +#[utoipa::path(get, path = "/groups/{group}/genotypes/{version}", + summary = "Metadata of one genotype version: labels, panel, markers", + description = "The header labels, the panel's individuals (and the strains a mapping \ +actually uses), the chromosomes and their marker counts -- without a single genotype call. \ +Equivalently: everything //groups/{group}/traits/{id}/values leaves you needing to build a \ +mapping request.", + params( + ("group" = String, Path, description = "InbredSet name, e.g. BXD"), + ("version" = String, Path, description = "Version from /groups/{group}/genotypes, e.g. BXD.8") + ), + responses( + (status = 200, description = "The version's metadata", body = Envelope<GenotypeDetail>), + Unauthorized, + (status = 404, description = "No such group or version", body = ApiError), + (status = 500, description = "The genotype file could not be read", body = ApiError) + ) +)] +#[gnauth(token_only)] +pub async fn group_genotype_version( + ctx: Ctx, + Path((group, version)): Path<(String, String)>, + _token: AuthToken, +) -> Result<Json<Envelope<GenotypeDetail>>, ApiError> { + let rid = ctx.request_info(); + let detail = resolve_detail(&group, &version, rid.clone()).await?; + let link_group = group.clone(); + let link_version = version.clone(); + Ok(Json( + ctx.envelope(detail) + .with_note( + "`individuals` is the whole file; `strains` is what a mapping uses, after the \ + default parents/F1s exclusion. Marker positions come from the file itself.", + ) + .with_next( + &format!( + "/groups/{}/genotypes/{}/markers", + path_segment(&link_group), + path_segment(&link_version) + ), + "The markers this version carries, paged (name, chr, cM, Mb)", + ) + .with_next( + &format!("/groups/{}", path_segment(&link_group)), + "The group's record", + ), + )) +} + +#[utoipa::path(get, path = "/groups/{group}/genotypes/{version}/markers", + summary = "The markers one genotype version carries, paged", + description = "Marker names and positions (chr, cM, Mb) only: enough to frame a mapping \ +result, not the genotype matrix. Filter with ?chr=1 and page with ?page/?limit.", + params( + ("group" = String, Path, description = "InbredSet name, e.g. BXD"), + ("version" = String, Path, description = "Version from /groups/{group}/genotypes"), + MarkerParams + ), + responses( + (status = 200, description = "A page of markers, positional rows (meta.columns names them)", body = Envelope<serde_json::Value>), + Unauthorized, + (status = 404, description = "No such group or version", body = ApiError), + (status = 422, description = "limit out of range", body = ApiError), + (status = 500, description = "The genotype file could not be read", body = ApiError) + ) +)] +#[gnauth(token_only)] +pub async fn group_genotype_markers( + ctx: Ctx, + Path((group, version)): Path<(String, String)>, + Query(params): Query<MarkerParams>, + _token: AuthToken, +) -> Result<Json<Envelope<serde_json::Value>>, ApiError> { + let rid = ctx.request_info(); + let limit = params.limit.unwrap_or(100).clamp(1, 10_000) as usize; + let page = params.page.unwrap_or(1).max(1) as usize; + let chr = params.chr.clone(); + + let directory = Config::load().genotype_files_dir; + let wanted_group = group.clone(); + let wanted_version = version.clone(); + let markers = tokio::task::spawn_blocking(move || { + let resolved = genotypes::resolve( + std::path::Path::new(&directory), + &wanted_group, + Some(&wanted_version), + )?; + genotypes::file_meta(&resolved.geno).map(|meta| meta.markers) + }) + .await + .map_err(|e| { + ApiError::new( + axum::http::StatusCode::INTERNAL_SERVER_ERROR, + "internal_error", + "Internal error", + e.to_string(), + "group_genotype_markers", + ) + .with_request_id(rid.clone()) + })? + .map_err(|e| genotype_error_to_api_error(e, "group_genotype_markers", rid.clone()))?; + + let filtered: Vec<genotypes::Marker> = markers + .into_iter() + .filter(|marker| chr.as_deref().is_none_or(|wanted| marker.chr == wanted)) + .collect(); + let total = filtered.len(); + let rows: Vec<serde_json::Value> = filtered + .into_iter() + .skip((page - 1) * limit) + .take(limit) + .map(|marker| serde_json::json!([marker.name, marker.chr, marker.cm, marker.mb])) + .collect(); + let num_rows = rows.len(); + + let mut envelope = ctx + .envelope(serde_json::Value::Array(rows)) + .with_columns( + ["name", "chr", "cM", "Mb"].iter().map(|s| s.to_string()).collect(), + num_rows, + ) + .with_note( + "Markers only: name, chromosome, cM and Mb from the genotype file. The genotypes \ + themselves are not served.", + ); + if let Some(chr) = &chr { + envelope = envelope.with_note(&format!( + "Filtered to chromosome {chr}: {total} markers." + )); + } + let pages = total.div_ceil(limit).max(1); + if page < pages { + envelope = envelope.with_next( + &format!( + "/groups/{}/genotypes/{}/markers?page={}&limit={}{}", + path_segment(&group), + path_segment(&version), + page + 1, + limit, + chr.as_deref() + .map(|c| format!("&chr={}", path_segment(c))) + .unwrap_or_default() + ), + "The next page of markers", + ); + } + envelope = envelope.with_next( + &format!( + "/groups/{}/genotypes/{}", + path_segment(&group), + path_segment(&version) + ), + "This version's metadata (labels, individuals, chromosomes)", + ); + Ok(Json(envelope)) +} + +/// Resolve a version and read its metadata; shared by the detail handler. +async fn resolve_detail( + group: &str, + version: &str, + rid: crate::response::RequestInfo, +) -> Result<GenotypeDetail, ApiError> { + let directory = Config::load().genotype_files_dir; + let group_owned = group.to_string(); + let version_owned = version.to_string(); + let wanted_group = group_owned.clone(); + let wanted_version = version_owned.clone(); + tokio::task::spawn_blocking(move || { + let dir = std::path::Path::new(&directory); + let resolved = genotypes::resolve(dir, &wanted_group, Some(&wanted_version))?; + let files = genotypes::list(dir, &wanted_group)?; + let listed = files + .iter() + .find(|file| file.version == resolved.version) + .map(|file| (file.title.clone(), file.gemma, file.rqtl, file.current)) + .unwrap_or((resolved.title.clone(), false, false, false)); + let meta = genotypes::file_meta(&resolved.geno)?; + let excluded = genotypes::non_strains(dir, &wanted_group, &meta.individuals); + let strains: Vec<String> = meta + .individuals + .iter() + .filter(|name| !excluded.contains(*name)) + .cloned() + .collect(); + let mut order: Vec<(String, usize)> = Vec::new(); + for marker in &meta.markers { + match order.iter_mut().find(|(name, _)| *name == marker.chr) { + Some((_, count)) => *count += 1, + None => order.push((marker.chr.clone(), 1)), + } + } + let num_individuals = meta.individuals.len(); + let num_strains = strains.len(); + Ok::<_, genotypes::GenotypeError>(GenotypeDetail { + group: wanted_group, + version: resolved.version.clone(), + file: format!("{}.geno", resolved.version), + title: listed.0, + labels: meta + .labels + .into_iter() + .map(|(key, value)| Label { key, value }) + .collect(), + individuals: meta.individuals, + num_individuals, + strains, + num_strains, + chromosomes: order + .into_iter() + .map(|(name, markers)| Chromosome { name, markers }) + .collect(), + markers: meta.markers.len(), + gemma: listed.1, + rqtl: listed.2, + current: listed.3, + }) + }) + .await + .map_err(|e| { + ApiError::new( + axum::http::StatusCode::INTERNAL_SERVER_ERROR, + "internal_error", + "Internal error", + e.to_string(), + "group_genotype_version", + ) + .with_request_id(rid.clone()) + })? + .map_err(|e| genotype_error_to_api_error(e, "group_genotype_version", rid)) +} + +/// A genotype resolution failure, as a caller-facing error. +fn genotype_error_to_api_error( + error: GenotypeError, + operation: &str, + rid: crate::response::RequestInfo, +) -> ApiError { + let (status, code, title) = match error { + GenotypeError::NotFound(_) => ( + axum::http::StatusCode::NOT_FOUND, + "genotypes_not_found", + "Genotype file not found", + ), + GenotypeError::Io(_) => ( + axum::http::StatusCode::INTERNAL_SERVER_ERROR, + "genotypes_unreadable", + "Genotype files could not be read", + ), + }; + ApiError::new(status, code, title, error.to_string(), operation).with_request_id(rid) +} + #[cfg(test)] mod tests { use super::*; fn version(name: &str, current: bool) -> GenotypeVersion { GenotypeVersion { + file: format!("{name}.geno"), version: name.to_string(), title: None, individuals: 198, @@ -186,7 +510,7 @@ mod tests { .unwrap(); let text = json.to_string(); assert!(!text.contains('/'), "no path-shaped value: {text}"); - assert!(!text.contains("geno"), "not even a file name: {text}"); + assert_eq!(json["versions"][0]["file"], "BXD.8.geno", "the file name is fine: {text}"); assert_eq!(json["versions"][0]["version"], "BXD.8"); assert_eq!(json["versions"][0]["current"], true); assert_eq!(json["versions"][1]["current"], false); |
