about summary refs log tree commit diff
path: root/src
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-07 17:35:44 +0000
committerPjotr <wrk@bosa.lan>2026-11-07 17:35:44 +0000
commit632cf0c61ee4602ee8423593a8aa8fd8a4373c41 (patch)
treeee81f60e0211f510969ac8122ac496048c5db87d /src
parent555fe06b0ab72240f254206f0f0c4ddf76ec00c5 (diff)
downloadgenenetwork4-632cf0c61ee4602ee8423593a8aa8fd8a4373c41.tar.gz
phewas: every trait peaking within a window of one position
PublishXRef records the marker each published trait's QTL peaks at
(Locus) with its LRS, which is a PheWAS waiting to happen: fix a
position, find the markers within a window of it, and ask which traits
peak at those markers.

  GET /groups/{group}/phewas?locus=rs30524230&window=10000
  GET /groups/{group}/phewas?chr=9&mb=29.940961&window=10000

The window is in base pairs, centred, default 10 kb either side -- the
"10K up and downstream" case. Positions come from the group's genotype
marker table (the endpoint added last round), so `genotype_version`
selects whose markers define the window and the answer reports them
alongside the traits: an empty `traits` list is then readable as
"nothing peaks that close" rather than a failure, and a ten-times wider
window is offered as `next`.

Measured on real data, ±10 kb around rs30524230 (chr 9, 29.94 Mb, a BXD
QTL peak at LRS 460): 4 markers, 10 traits, from LOD 99.9 down to 2.68 --
ANPEP_band, then microbiome/haematology/infectious-disease traits. That
cluster of 99.9s is the 460 LRS cap, not a spectrum, which the notes say.

* src/db.rs (get_phewas_traits): PublishXRef rows for a set of peak
markers, joining Phenotype/Publication through the existing
trait_info_sql, strongest first; marker names are re-validated before
they reach the IN list.
* src/routes/phewas.rs: the endpoint, token-gated; window/centre
validation (422 for none or negative), 404 for an unknown locus, notes
for the empty cases, and a unit test for the version/group helper.
* tests/phewas.rs: markers in the window, traits sorted by LRS with
lod = lrs/4.604, every hit peaking at a listed marker, zero-width window,
the two failure modes, and that the suggested wider window resolves.
* README.md, docs/www/ai-instruction.md (new 4b: how to read a PheWAS),
docs/www/operator-checklist.md: the endpoint and its reading.
Diffstat (limited to 'src')
-rw-r--r--src/db.rs57
-rw-r--r--src/lib.rs1
-rw-r--r--src/routes/mod.rs1
-rw-r--r--src/routes/phewas.rs386
4 files changed, 445 insertions, 0 deletions
diff --git a/src/db.rs b/src/db.rs
index ecc19fd..1d2b0f7 100644
--- a/src/db.rs
+++ b/src/db.rs
@@ -632,6 +632,63 @@ pub fn get_group_traits_by_abbreviation(
     .map_err(DbError::from)
 }
 
+/// Published traits of a group whose peak marker is one of `loci`,
+/// strongest first -- a PheWAS at one locus.
+///
+/// `PublishXRef.Locus` is the marker a trait's QTL peaks at, so this is
+/// "every trait peaking at these markers", which combined with a window
+/// around one position (see src/routes/phewas.rs) is a PheWAS around that
+/// position.
+pub fn get_phewas_traits(group_id: u16, loci: &[String]) -> Result<Vec<TraitInfo>, DbError> {
+    if loci.is_empty() {
+        return Ok(Vec::new());
+    }
+    // Only names that came out of the deployment's marker table reach
+    // here, and they are re-checked anyway: a marker name is
+    // alphanumeric plus `_.:-`, so a quote can never get into the IN
+    // list below.
+    let safe: Vec<&str> = loci
+        .iter()
+        .map(String::as_str)
+        .filter(|locus| {
+            !locus.is_empty()
+                && locus
+                    .chars()
+                    .all(|c| c.is_ascii_alphanumeric() || "_.:-".contains(c))
+        })
+        .collect();
+    if safe.is_empty() {
+        return Ok(Vec::new());
+    }
+    let pool = pool()?;
+    let mut conn = pool.get_conn()?;
+    let mut traits = Vec::new();
+    // Keep the IN list modest for the query planner, and the result
+    // order stable across chunks by sorting once at the end.
+    for chunk in safe.chunks(200) {
+        let list = chunk
+            .iter()
+            .map(|locus| format!("'{locus}'"))
+            .collect::<Vec<_>>()
+            .join(",");
+        let mut rows: Vec<TraitInfo> = conn.exec(
+            trait_info_sql(
+                &format!("PublishXRef.InbredSetId = :group_id AND PublishXRef.Locus IN ({list})"),
+                "PublishXRef.LRS DESC",
+            ),
+            mysql::params! { "group_id" => group_id },
+        )?;
+        traits.append(&mut rows);
+    }
+    traits.sort_by(|a, b| {
+        b.lrs
+            .unwrap_or(0.0)
+            .partial_cmp(&a.lrs.unwrap_or(0.0))
+            .unwrap_or(std::cmp::Ordering::Equal)
+    });
+    Ok(traits)
+}
+
 /// Every published trait (across groups) reported in the publication
 /// with this PubMed id, or None when no such publication exists.
 pub fn get_publication_traits(pubmed_id: u32) -> Result<Option<Vec<TraitInfo>>, DbError> {
diff --git a/src/lib.rs b/src/lib.rs
index 8fdda89..96b7b5a 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -84,6 +84,7 @@ pub fn app() -> Router {
         .routes(routes!(routes::publications::publication_traits))
         .routes(routes!(routes::search::search))
         .routes(routes!(routes::correlation::correlation))
+        .routes(routes!(routes::phewas::group_phewas))
         .routes(routes!(routes::genotypes::group_genotypes))
         .routes(routes!(routes::genotypes::group_genotype_version))
         .routes(routes!(routes::genotypes::group_genotype_markers))
diff --git a/src/routes/mod.rs b/src/routes/mod.rs
index e6926f1..5407fea 100644
--- a/src/routes/mod.rs
+++ b/src/routes/mod.rs
@@ -11,6 +11,7 @@ pub mod gemma;
 pub mod genotypes;
 pub mod groups;
 pub mod mapping_methods;
+pub mod phewas;
 pub mod publications;
 pub mod rqtl;
 pub mod search;
diff --git a/src/routes/phewas.rs b/src/routes/phewas.rs
new file mode 100644
index 0000000..b5eb45a
--- /dev/null
+++ b/src/routes/phewas.rs
@@ -0,0 +1,386 @@
+//! `GET /groups/{group}/phewas` -- every published trait whose QTL peaks
+//! within a window of one chromosomal position.
+//!
+//! `PublishXRef.Locus` is the marker each published trait's QTL peaks at,
+//! so "traits peaking at these markers" is a PheWAS around a position
+//! once the marker table says which markers fall in the window. Both
+//! halves are already here: the marker table from the group's genotype
+//! file (`src/genotypes.rs`) and the traits from the database
+//! (`db::get_phewas_traits`).
+//!
+//! The window is in **base pairs** and centred on the position, so
+//! `window=10000` means 10 kb up- and downstream. Marker spacing in a
+//! panel is what decides whether anything is in it -- on BXD's WGS panel
+//! the median gap is well under a kilobase in dense regions but sparse
+//! elsewhere, so an empty answer is information, not an error, and the
+//! response says how many markers were in the window.
+
+use axum::Json;
+use axum::extract::{Path, Query};
+use gnauth_macros::gnauth;
+use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use crate::auth::AuthToken;
+use crate::config::Config;
+use crate::db;
+use crate::error::{ApiError, Unauthorized};
+use crate::genotypes;
+use crate::response::{Ctx, Envelope, path_segment};
+
+/// The window and its centre.
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct PhewasParams {
+    /// Centre the window on this marker, e.g. a QTL peak from a mapping.
+    /// Takes precedence over `chr`/`mb`.
+    pub locus: Option<String>,
+    /// Chromosome, e.g. "9". Required unless `locus` is given.
+    pub chr: Option<String>,
+    /// Position on `chr`, in megabases -- the unit mappings report.
+    /// Required unless `locus` is given.
+    pub mb: Option<f64>,
+    /// Half-width of the window in base pairs: 10000 means 10 kb either
+    /// side. Default 10000.
+    pub window: Option<f64>,
+    /// Genotype version whose marker table defines the window; defaults
+    /// to the group's current one (see /groups/{group}/genotypes).
+    pub genotype_version: Option<String>,
+}
+
+/// A trait whose QTL peak is in the window.
+#[derive(Serialize, ToSchema)]
+pub struct PhewasHit {
+    /// `PublishXRef.Id` -- the trait's id within its group.
+    pub trait_id: u32,
+    pub phenotype_id: u16,
+    /// The PublishFreeze the trait belongs to, e.g. "BXDPublish".
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub dataset: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub abbreviation: Option<String>,
+    /// Post-publication description, else pre-publication, else original.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    /// The marker this trait peaks at -- the one that put it in the window.
+    pub locus: String,
+    pub chr: String,
+    pub mb: f64,
+    pub lrs: f64,
+    pub lod: f64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub mean: Option<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub additive: Option<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub nsamples: Option<i32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub pubmed_id: Option<u32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub url: Option<String>,
+}
+
+/// A marker the window covers.
+#[derive(Serialize, ToSchema)]
+pub struct WindowMarker {
+    pub name: String,
+    pub mb: f64,
+}
+
+/// The PheWAS result.
+#[derive(Serialize, ToSchema)]
+pub struct Phewas {
+    pub group: String,
+    /// The genotype version whose marker table was used.
+    pub genotype_version: String,
+    /// The window's centre.
+    pub centre: Centre,
+    /// Half-width, in base pairs.
+    pub window_bp: f64,
+    /// Markers in the window; the traits below peak at one of them.
+    pub markers: Vec<WindowMarker>,
+    /// Traits peaking in the window, strongest first.
+    pub traits: Vec<PhewasHit>,
+}
+
+/// Where the window is centred.
+#[derive(Serialize, ToSchema)]
+pub struct Centre {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub locus: Option<String>,
+    pub chr: String,
+    pub mb: f64,
+}
+
+#[utoipa::path(get, path = "/groups/{group}/phewas",
+    summary = "PheWAS: every published trait peaking within a window of one position",
+    description = "Finds the markers within `window` base pairs of a chromosomal position -- \
+given either as `locus` (a marker name, e.g. a QTL peak) or as `chr` + `mb` -- and returns \
+every published trait of the group whose `PublishXRef.Locus` is one of them, strongest first. \
+The window is centred on the position: `window=10000` is 10 kb up- and downstream. An empty \
+`traits` list is a real answer (no trait peaks that close), and `markers` says how many \
+markers were in the window.",
+    params(("group" = String, Path, description = "InbredSet name, e.g. BXD"), PhewasParams),
+    responses(
+        (status = 200, description = "The traits peaking in the window, with the markers found", body = Envelope<Phewas>),
+        Unauthorized,
+        (status = 404, description = "No such group, genotype version, or locus", body = ApiError),
+        (status = 422, description = "Neither locus nor chr+mb given, or a negative window", body = ApiError),
+        (status = 503, description = "Database unavailable", body = ApiError),
+        (status = 500, description = "Database or genotype-file error", body = ApiError)
+    )
+)]
+#[gnauth(token_only)]
+pub async fn group_phewas(
+    ctx: Ctx,
+    Path(group): Path<String>,
+    Query(params): Query<PhewasParams>,
+    _token: AuthToken,
+) -> Result<Json<Envelope<Phewas>>, ApiError> {
+    let rid = ctx.request_info();
+    let window_bp = params.window.unwrap_or(10_000.0);
+    if !(window_bp.is_finite() && window_bp >= 0.0) {
+        return Err(ApiError::new(
+            axum::http::StatusCode::UNPROCESSABLE_ENTITY,
+            "invalid_window",
+            "Invalid window",
+            format!("window must be a non-negative number of base pairs (got {window_bp})."),
+            "group_phewas",
+        )
+        .with_request_id(rid));
+    }
+
+    let directory = Config::load().genotype_files_dir;
+    let group_for_lookup = group.clone();
+    let version = params.genotype_version.clone();
+    let locus = params.locus.clone();
+    let given_chr = params.chr.clone();
+    let given_mb = params.mb;
+
+    let resolved_window = tokio::task::spawn_blocking(move || {
+        let dir = std::path::Path::new(&directory);
+        let resolved = genotypes::resolve(dir, &group_for_lookup, version.as_deref())?;
+        let meta = genotypes::file_meta(&resolved.geno)?;
+        let centre = match (&locus, &given_chr, given_mb) {
+            (Some(locus), _, _) => {
+                let marker = meta.markers.iter().find(|marker| &marker.name == locus);
+                match marker.and_then(|marker| marker.mb.map(|mb| (marker, mb))) {
+                    Some((marker, mb)) => (Some(marker.name.clone()), marker.chr.clone(), mb),
+                    None => {
+                        return Err(genotypes::GenotypeError::NotFound(format!(
+                            "no marker '{locus}' with a position in this genotype version; \
+                             pass chr and mb instead, or check the name with \
+                             /groups/{}/genotypes/{}/markers",
+                            resolved_geno_group(&resolved.version),
+                            resolved.version
+                        )));
+                    }
+                }
+            }
+            (None, Some(chr), Some(mb)) => (None, chr.clone(), mb),
+            _ => {
+                return Err(genotypes::GenotypeError::NotFound(
+                    "give either locus, or chr and mb".to_string(),
+                ));
+            }
+        };
+        let (centre_locus, centre_chr, centre_mb) = centre;
+        let half = window_bp / 1_000_000.0;
+        let mut markers: Vec<genotypes::Marker> = meta
+            .markers
+            .into_iter()
+            .filter(|marker| {
+                marker.chr == centre_chr
+                    && marker
+                        .mb
+                        .is_some_and(|mb| (mb - centre_mb).abs() <= half)
+            })
+            .collect();
+        markers.sort_by(|a, b| {
+            a.mb
+                .unwrap_or(0.0)
+                .partial_cmp(&b.mb.unwrap_or(0.0))
+                .unwrap_or(std::cmp::Ordering::Equal)
+        });
+        Ok::<_, genotypes::GenotypeError>((
+            resolved.version,
+            centre_locus,
+            centre_chr,
+            centre_mb,
+            markers,
+        ))
+    })
+    .await
+    .map_err(|e| {
+        ApiError::new(
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            "internal_error",
+            "Internal error",
+            e.to_string(),
+            "group_phewas",
+        )
+        .with_request_id(rid.clone())
+    })?
+    .map_err(|e| match e {
+        genotypes::GenotypeError::Io(message) => ApiError::new(
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            "genotypes_unreadable",
+            "Genotype files could not be read",
+            message,
+            "group_phewas",
+        )
+        .with_request_id(rid.clone()),
+        genotypes::GenotypeError::NotFound(message) if message.starts_with("give either") => {
+            ApiError::new(
+                axum::http::StatusCode::UNPROCESSABLE_ENTITY,
+                "missing_position",
+                "No position given",
+                message,
+                "group_phewas",
+            )
+            .with_request_id(rid.clone())
+        }
+        genotypes::GenotypeError::NotFound(message) => ApiError::new(
+            axum::http::StatusCode::NOT_FOUND,
+            "not_found",
+            "Not found",
+            message,
+            "group_phewas",
+        )
+        .with_request_id(rid.clone()),
+    })?;
+
+    let (version, centre_locus, centre_chr, centre_mb, markers) = resolved_window;
+    let loci: Vec<String> = markers.iter().map(|marker| marker.name.clone()).collect();
+    let group_for_db = group.clone();
+    let traits_found = tokio::task::spawn_blocking(move || {
+        let group_row = db::get_group_by_name(&group_for_db)?;
+        match group_row {
+            Some(group_row) => db::get_phewas_traits(group_row.id, &loci),
+            None => Ok(Vec::new()),
+        }
+    })
+    .await
+    .map_err(|e| {
+        ApiError::new(
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            "internal_error",
+            "Internal error",
+            e.to_string(),
+            "group_phewas",
+        )
+        .with_request_id(rid.clone())
+    })?
+    .map_err(|e| ApiError::from_db(e, "group_phewas").with_request_id(rid.clone()))?;
+
+    // Marker name -> position, so each hit carries where it peaks.
+    let positions: std::collections::HashMap<&str, (String, f64)> = markers
+        .iter()
+        .filter_map(|marker| {
+            marker
+                .mb
+                .map(|mb| (marker.name.as_str(), (marker.chr.clone(), mb)))
+        })
+        .collect();
+    let hits: Vec<PhewasHit> = traits_found
+        .into_iter()
+        .filter_map(|trait_info| {
+            let locus = trait_info.locus.clone()?;
+            let (chr, mb) = positions.get(locus.as_str())?.clone();
+            Some(PhewasHit {
+                description: trait_info
+                    .post_publication_description
+                    .clone()
+                    .or_else(|| trait_info.pre_publication_description.clone())
+                    .or_else(|| trait_info.original_description.clone()),
+                trait_id: trait_info.id,
+                phenotype_id: trait_info.phenotype_id,
+                dataset: trait_info.dataset.clone(),
+                abbreviation: trait_info.abbreviation.clone(),
+                locus,
+                chr,
+                mb,
+                lrs: trait_info.lrs.unwrap_or(0.0),
+                lod: trait_info.lod.unwrap_or(0.0),
+                mean: trait_info.mean,
+                additive: trait_info.additive,
+                nsamples: trait_info.nsamples,
+                pubmed_id: trait_info.pubmed_id,
+                url: trait_info.url.clone(),
+            })
+        })
+        .collect();
+
+    let mut envelope = ctx
+        .envelope(Phewas {
+            group: group.clone(),
+            genotype_version: version.clone(),
+            centre: Centre {
+                locus: centre_locus,
+                chr: centre_chr.clone(),
+                mb: centre_mb,
+            },
+            window_bp,
+            markers: markers
+                .iter()
+                .filter_map(|marker| {
+                    marker.mb.map(|mb| WindowMarker {
+                        name: marker.name.clone(),
+                        mb,
+                    })
+                })
+                .collect(),
+            traits: hits,
+        })
+        .with_note(
+            "lod = lrs / 4.604. The window is centred on the position, so window=10000 covers \
+             10 kb either side; a trait is in it when its PublishXRef peak marker is one of the \
+             markers listed.",
+        );
+    if markers.is_empty() {
+        envelope = envelope.with_note(
+            "No marker of this genotype version falls in the window, so no trait can be \
+             reported: widen `window`, or check the position against \
+             /groups/{group}/genotypes/{version}/markers.",
+        );
+    }
+    envelope = envelope
+        .with_next(
+            &format!("/groups/{}", path_segment(&group)),
+            "The group's record",
+        )
+        .with_next(
+            &format!(
+                "/groups/{}/phewas?{}&window={}",
+                path_segment(&group),
+                match params.locus.as_deref() {
+                    Some(locus) => format!("locus={}", path_segment(locus)),
+                    None => format!(
+                        "chr={}&mb={}",
+                        path_segment(&centre_chr),
+                        centre_mb
+                    ),
+                },
+                window_bp * 10.0
+            ),
+            "The same PheWAS with a ten-times wider window",
+        );
+    Ok(Json(envelope))
+}
+
+/// The group name a version stem belongs to, for error messages: `BXD.8`
+/// belongs to `BXD`.
+fn resolved_geno_group(version: &str) -> &str {
+    version.split('.').next().unwrap_or(version)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::resolved_geno_group;
+
+    #[test]
+    fn the_group_name_is_the_stem_before_the_first_dot() {
+        assert_eq!(resolved_geno_group("BXD.8"), "BXD");
+        assert_eq!(resolved_geno_group("HET3-ITP.12"), "HET3-ITP");
+        assert_eq!(resolved_geno_group("BXD"), "BXD");
+    }
+}