diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-07 17:35:44 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-07 17:35:44 +0000 |
| commit | 632cf0c61ee4602ee8423593a8aa8fd8a4373c41 (patch) | |
| tree | ee81f60e0211f510969ac8122ac496048c5db87d /src | |
| parent | 555fe06b0ab72240f254206f0f0c4ddf76ec00c5 (diff) | |
| download | genenetwork4-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.rs | 57 | ||||
| -rw-r--r-- | src/lib.rs | 1 | ||||
| -rw-r--r-- | src/routes/mod.rs | 1 | ||||
| -rw-r--r-- | src/routes/phewas.rs | 386 |
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(¢re_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"); + } +} |
