about summary refs log tree commit diff
path: root/src
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-07 17:10:28 +0000
committerPjotr <wrk@bosa.lan>2026-11-07 17:10:28 +0000
commit18d18b1c125c06dd67dcf54ccbd89eb128643737 (patch)
treeefefbdc30000ff459a46457239bc9fb01035d642 /src
parent1f61f8f86443de6353295f7363abbe1c986d863f (diff)
downloadgenenetwork4-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.rs114
-rw-r--r--src/lib.rs2
-rw-r--r--src/routes/genotypes.rs330
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);