//! `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, /// Chromosome, e.g. "9". Required unless `locus` is given. pub chr: Option, /// Position on `chr`, in megabases -- the unit mappings report. /// Required unless `locus` is given. pub mb: Option, /// Half-width of the window in base pairs: 10000 means 10 kb either /// side. Default 10000. pub window: Option, /// Genotype version whose marker table defines the window; defaults /// to the group's current one (see /groups/{group}/genotypes). pub genotype_version: Option, } /// 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, #[serde(skip_serializing_if = "Option::is_none")] pub abbreviation: Option, /// Post-publication description, else pre-publication, else original. #[serde(skip_serializing_if = "Option::is_none")] pub description: Option, /// 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, #[serde(skip_serializing_if = "Option::is_none")] pub additive: Option, #[serde(skip_serializing_if = "Option::is_none")] pub nsamples: Option, #[serde(skip_serializing_if = "Option::is_none")] pub pubmed_id: Option, #[serde(skip_serializing_if = "Option::is_none")] pub url: Option, } /// 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, /// Traits peaking in the window, strongest first. pub traits: Vec, } /// Where the window is centred. #[derive(Serialize, ToSchema)] pub struct Centre { #[serde(skip_serializing_if = "Option::is_none")] pub locus: Option, 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), 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, Query(params): Query, _token: AuthToken, ) -> Result>, 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 = 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::Invalid(message) => ApiError::new( axum::http::StatusCode::UNPROCESSABLE_ENTITY, "invalid_individuals", "Unusable individual selection", message, "group_phewas", ) .with_request_id(rid.clone()), 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 = 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 = 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.with_links(crate::suggest::root_links()))) } /// 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"); } }