//! `GET /groups/{group}/traits/{trait_id}/peak-genotypes`: the genotypes of the //! animals at one marker of a **confirmed** hit. //! //! Returning genotypes is the one thing this API otherwise never does, so it //! is fenced: the marker has to be at the peak of a scan the server just ran, //! the peak has to clear a LOD threshold, and only animals that have a value //! for that trait get a call. That is exactly what is needed to draw a trait by //! genotype class (R/qtl's book, Fig 4.1) and nothing more -- the rest of the //! matrix stays where it is. //! //! The scan is re-run rather than trusted: a client naming a marker is asking //! the server to confirm the hit, so `/compute/rqtl`'s own machinery runs over //! the group's current (or named) version and the peak is measured here. use axum::Json; use axum::extract::{Path, Query}; use axum::http::StatusCode; use serde::Deserialize; use serde_json::Value; use gnauth_macros::{compute_gate, gnauth}; use crate::auth::AuthToken; use crate::compute_gate as gate; use crate::config::Config; use crate::error::{ApiError, Unauthorized}; use crate::frequencies; use crate::genotypes; use crate::response::{Ctx, Envelope, RequestInfo}; use crate::rqtl::{self, Sample}; #[derive(Deserialize, utoipa::IntoParams)] pub struct PeakGenotypeParams { /// The marker to return calls for -- typically the peak the mapping found. pub marker: String, /// How far (Mb) the marker may sit from the scan's own peak. Default 10. pub window: Option, /// The LOD the peak must reach. Default 3.0: below this there is no hit to /// confirm. pub min_lod: Option, /// The genotype version, default the group's current one. pub genotype_version: Option, } /// One animal at the marker. #[derive(serde::Serialize, utoipa::ToSchema)] pub struct CalledAnimal { pub individual: String, /// The call as the genotype file spells it (`B`, `D`, `H`, …). pub genotype: String, /// Its value for the trait, on the trait's own scale. pub value: f64, } #[utoipa::path(get, path = "/groups/{group}/traits/{trait_id}/peak-genotypes", summary = "Genotypes at one marker of a confirmed hit, for animals with a value", description = "Returns the genotype call of each animal **that has a value for this trait** \ at one marker -- the data behind a trait-by-genotype plot. It is fenced: the server re-runs \ the R/qtl scan for the trait, and the marker is only answered if it lies within `window` Mb of \ that scan's peak and the peak reaches `min_lod`. No other genotypes are returned, and nothing \ of the matrix beyond these calls.", params( ("group" = String, Path, description = "InbredSet name, e.g. DOL"), ("trait_id" = u32, Path, description = "Trait id within the group"), PeakGenotypeParams ), responses( (status = 200, description = "The marker, its scan statistics, and one call per animal with a value", body = Envelope), Unauthorized, (status = 403, description = "The trait is not public and you are not authorized", body = ApiError), (status = 404, description = "No such group, trait, version or marker", body = ApiError), (status = 422, description = "The marker is not at a confirmed hit", body = ApiError) ) )] #[gnauth(secured)] #[compute_gate(rqtl, label = "peak genotypes")] pub async fn peak_genotypes( ctx: Ctx, token: AuthToken, Path((group, trait_id)): Path<(String, u32)>, Query(params): Query, ) -> Result>, ApiError> { let rid = ctx.request_info(); let config = Config::load(); let marker = params.marker.clone(); let window = params.window.unwrap_or(10.0).abs(); let min_lod = params.min_lod.unwrap_or(3.0); // The trait's values, with its own authorization. let auth_server_url = config.auth_server_url.clone(); let group_for_values = group.clone(); let values = tokio::task::spawn_blocking(move || { crate::routes::groups::get_group_trait_values_result( &group_for_values, trait_id, &auth_server_url, &token, ) }) .await .map_err(|error| internal(error.to_string(), rid.clone()))?; let values = match values { Ok(crate::routes::groups::GroupTraitLookup::Found(authorized, values)) => { let _: crate::auth::Authorized = authorized; values } Ok(crate::routes::groups::GroupTraitLookup::Forbidden) => { return Err(ApiError::new( StatusCode::FORBIDDEN, "forbidden", "Not authorized", format!("trait {trait_id} is not public, and you are not authorized to view it."), "peak_genotypes", ) .with_request_id(rid)); } Ok(crate::routes::groups::GroupTraitLookup::GroupNotFound) => { return Err(ApiError::new( StatusCode::NOT_FOUND, "group_not_found", "Group not found", format!("No group matching '{group}'."), "peak_genotypes", ) .with_request_id(rid)); } Ok(crate::routes::groups::GroupTraitLookup::TraitNotFound) => { return Err(ApiError::new( StatusCode::NOT_FOUND, "trait_not_found", "Trait not found", format!("No trait {trait_id} in group '{group}'."), "peak_genotypes", ) .with_request_id(rid)); } Err(crate::routes::groups::GroupAuthError::Db(error)) => { return Err(ApiError::from_db(error, "peak_genotypes").with_request_id(rid)) } Err(crate::routes::groups::GroupAuthError::Auth(detail)) => { return Err(ApiError::new( StatusCode::BAD_GATEWAY, "auth_server_error", "Could not check authorization", detail, "peak_genotypes", ) .with_request_id(rid)); } }; let samples: Vec = values .iter() .map(|value| Sample { name: value.name.clone(), value: value.value, }) .collect(); let trait_label = format!("{group}::{trait_id}"); // The scan: the same path /compute/rqtl takes for a group request. let directory = config.genotype_files_dir.clone(); let cache_dir = config.rqtl_cache_dir.clone(); let wrapper = config.rqtl_wrapper_path.clone(); let group_for_scan = group.clone(); let version = params.genotype_version.clone(); let values_by_name: Vec<(String, Option)> = samples .iter() .map(|sample| (sample.name.clone(), sample.value)) .collect(); let values_for_scan = values_by_name.clone(); let cache_dir_for_scan = cache_dir.clone(); let trait_for_scan = trait_label.clone(); let scan = tokio::task::spawn_blocking(move || { let resolved = genotypes::resolve(std::path::Path::new(&directory), &group_for_scan, version.as_deref()) .map_err(|error| error.to_string())?; let excluded = genotypes::non_strains( std::path::Path::new(&directory), &group_for_scan, &resolved.panel, ); let keep: Vec = resolved .panel .iter() .enumerate() .filter(|(_, name)| !excluded.contains(*name)) .map(|(index, _)| index) .collect(); let (aligned, _matched) = genotypes::align(&resolved.panel, &keep, &values_for_scan); let prepared = genotypes::prepare( std::path::Path::new(&directory), &resolved, genotypes::Engine::Rqtl, &keep, std::path::Path::new(&cache_dir_for_scan), ) .map_err(|error| error.to_string())?; let names: Vec = keep.iter().map(|index| resolved.panel[*index].clone()).collect(); let samples: Vec = names .into_iter() .zip(aligned) .map(|(name, value)| Sample { name, value }) .collect(); Ok::<_, String>((resolved.geno.clone(), resolved.version.clone(), prepared, samples)) }) .await .map_err(|error| internal(error.to_string(), rid.clone()))? .map_err(|error| { ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "genotype_error", "The genotype files could not be read", error, "peak_genotypes", ) .with_request_id(rid.clone()) })?; let (geno, version_used, prepared, mapped_samples) = scan; let prepared_genotype_file = prepared.genotype_file.to_string_lossy().into_owned(); let output = rqtl::compute( &wrapper, &cache_dir, &prepared_genotype_file, &trait_for_scan, &mapped_samples, &[], "normal", "hk", 0, "Mb", None, None, ) .await .map_err(|error| { ApiError::new( StatusCode::BAD_GATEWAY, "rqtl_failed", "R/qtl computation failed", error.to_string(), "peak_genotypes", ) .with_request_id(rid.clone()) })?; let Some(peak) = output.markers.iter().max_by(|left, right| { left.lod.partial_cmp(&right.lod).unwrap_or(std::cmp::Ordering::Equal) }) else { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "no_scan", "The scan produced no markers", "the genotype version has nothing to scan".to_string(), "peak_genotypes", ) .with_request_id(rid)); }; if peak.lod < min_lod { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "not_a_hit", "No confirmed hit to report", format!( "this trait's strongest marker is {} (chr{}, {:.2} Mb) at LOD {:.2}, below the \ {min_lod} needed to confirm a hit", peak.name, peak.chr, peak.pos, peak.lod ), "peak_genotypes", ) .with_request_id(rid)); } // The marker has to be at *this* peak: a far-away marker is not covered by // whatever the scan confirmed. let Some(requested) = output .markers .iter() .find(|candidate| candidate.name == marker) else { return Err(ApiError::new( StatusCode::NOT_FOUND, "marker_not_found", "Marker not in this scan", format!("no marker '{marker}' in the scan of {group}'s genotype version"), "peak_genotypes", ) .with_request_id(rid)); }; let distance = if requested.chr == peak.chr { (requested.pos - peak.pos).abs() } else { f64::INFINITY }; if distance > window { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "not_the_peak", "That marker is not at the confirmed peak", format!( "the scan peaks at {} (chr{}, {:.2} Mb, LOD {:.2}); {marker} is {distance:.1} Mb \ away{}. Genotypes are only returned at a confirmed hit", peak.name, peak.chr, peak.pos, peak.lod, if distance.is_finite() { String::new() } else { format!(" (chromosome {})", requested.chr) } ), "peak_genotypes", ) .with_request_id(rid)); } // The calls, for the animals that have a value. Nothing else leaves. let geno_path = geno.clone(); let wanted_marker = marker.clone(); let calls = tokio::task::spawn_blocking(move || { frequencies::marker_calls(&geno_path, &wanted_marker) }) .await .map_err(|error| internal(error.to_string(), rid.clone()))? .map_err(|error| { ApiError::new( StatusCode::NOT_FOUND, "marker_not_found", "Marker not found", error.to_string(), "peak_genotypes", ) .with_request_id(rid.clone()) })?; let by_name: std::collections::HashMap<&str, Option> = samples .iter() .map(|sample| (sample.name.as_str(), sample.value)) .collect(); let mut animals: Vec = Vec::new(); for (individual, call) in &calls.calls { let (Some(call), Some(Some(value))) = (call, by_name.get(individual.as_str())) else { continue; }; animals.push(CalledAnimal { individual: individual.clone(), genotype: call.clone(), value: *value, }); } if animals.is_empty() { return Err(ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "no_called_animals", "No animal with a value carries a call here", format!("marker {marker} has no calls for the animals with a value for this trait"), "peak_genotypes", ) .with_request_id(rid)); } let mut counts: std::collections::BTreeMap = std::collections::BTreeMap::new(); for animal in &animals { *counts.entry(animal.genotype.clone()).or_insert(0) += 1; } let mut envelope = ctx .envelope(serde_json::json!({ "marker": marker, "chr": requested.chr, "pos": requested.pos, "lod": (requested.lod * 1000.0).round() / 1000.0, "peak": {"marker": peak.name, "chr": peak.chr, "pos": peak.pos, "lod": (peak.lod * 1000.0).round() / 1000.0}, "window_mb": window, "genotype_version": version_used, "counts": counts, "animals": animals, })) .with_note(&format!( "Confirmed by a scan this request ran: {group}'s genotype version {} peaks at {} \ (chr{}, {:.2} Mb) with LOD {:.2}, and {marker} is {:.1} Mb from it.", version_used, peak.name, peak.chr, peak.pos, peak.lod, distance )) .with_note( "Only animals that have a value for this trait are listed, and only this marker's \ calls -- the rest of the genotype matrix is not returned. Widen the confirmation \ with ?window= (Mb) or ?min_lod=; a marker away from the peak is refused.", ); envelope = envelope.with_action(crate::response::SuggestedCall { method: "POST".to_string(), href: "/plot/genotypes".to_string(), description: "Draw the trait by genotype class: post this reply's data with the trait's \ values (see `next`)." .to_string(), body: None, }); envelope = envelope.with_next( &format!("/groups/{}/traits/{trait_id}/values", crate::response::path_segment(&group)), "The trait's values, to post with this reply to /plot/genotypes", ); Ok(Json(envelope)) } fn internal(message: String, rid: RequestInfo) -> ApiError { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", message, "peak_genotypes", ) .with_request_id(rid) }