//! Groups (InbredSet) domain endpoints: read-only access to the //! InbredSet table and its strains. use axum::Json; use axum::extract::{Path, Query}; use axum::http::StatusCode; use serde::{Deserialize, Serialize}; use utoipa::ToSchema; use gnauth_macros::gnauth; use crate::auth::{self, AuthToken, Authorized}; use crate::config::Config; use crate::db; use crate::normalize; use crate::error::{ApiError, Unauthorized}; use crate::genotypes; use crate::response::{Ctx, Envelope, path_segment}; use crate::suggest; /// Query parameters for `GET /groups`; all optional, combined with AND. #[derive(Deserialize, utoipa::IntoParams)] pub struct GroupsParams { /// Keep groups whose family contains this text, case-insensitively, /// e.g. "Reference Populations". pub family: Option, /// Keep groups of this species, by the short name /species lists /// (case-insensitive), e.g. "mouse". pub species: Option, /// Keep groups whose name, display name or full name contains this /// text, case-insensitively, e.g. "alzheimer". pub q: Option, } fn contains_ci(field: &Option, needle: &str) -> bool { field .as_deref() .is_some_and(|f| f.to_lowercase().contains(&needle.to_lowercase())) } #[utoipa::path(get, path = "/groups", summary = "List all groups (populations; InbredSet rows), optionally filtered", params(GroupsParams), responses( (status = 200, description = "The groups (InbredSet rows), with family and species name", body = Envelope>), Unauthorized, (status = 500, description = "Database error", body = ApiError) ))] #[gnauth(token_only)] pub async fn groups( ctx: Ctx, _token: AuthToken, Query(params): Query, ) -> Result>>, ApiError> { let rid = ctx.request_info(); tokio::task::spawn_blocking(db::get_all_groups) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "groups", ) .with_request_id(rid.clone()) })? .map(|groups| { let groups: Vec = groups .into_iter() .filter(|g| { params .family .as_ref() .is_none_or(|f| contains_ci(&g.family, f)) }) .filter(|g| { params.species.as_ref().is_none_or(|s| { g.species .as_deref() .is_some_and(|n| n.eq_ignore_ascii_case(s)) }) }) .filter(|g| { params.q.as_ref().is_none_or(|q| { contains_ci(&Some(g.name.clone()), q) || contains_ci(&g.display_name, q) || contains_ci(&g.full_name, q) }) }) .collect(); Json(ctx.envelope(groups).with_next( "/species", "The species the groups belong to (filter groups with ?species=)", )) }) .map_err(|e| ApiError::from_db(e, "groups").with_request_id(rid)) } #[utoipa::path(get, path = "/groups/{group}", summary = "Get one group's full record by name or numeric id", params( ("group" = String, Path, description = "Group InbredSetName, Name, FullName or numeric Id") ), responses( (status = 200, description = "The matching row of the InbredSet table", body = Envelope), Unauthorized, (status = 404, description = "No matching group", body = ApiError), (status = 500, description = "Database error", body = ApiError) ))] #[gnauth(token_only)] pub async fn group_by_name( ctx: Ctx, Path(group): Path, _token: AuthToken, ) -> Result>, ApiError> { let rid = ctx.request_info(); let not_found_name = group.clone(); tokio::task::spawn_blocking(move || db::get_group_by_name(&group)) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "group_by_name", ) .with_request_id(rid.clone()) })? .map_err(|e| ApiError::from_db(e, "group_by_name").with_request_id(rid.clone()))? .map(|detail| { let name = path_segment(&detail.name); // The parental design is metadata a caller usually wants with the // group itself: "which cross is this?" is answered by two strain // names, not by a second request. The full design -- the F1s' // individuals, what a mapping drops -- is the endpoint below. let design = { let directory = std::path::PathBuf::from(&Config::load().genotype_files_dir); genotypes::parental_design(&directory, &detail.name, None, None) }; let design_note = { let maternal = design .maternal .as_ref() .map(|role| role.strain.clone()) .unwrap_or_else(|| "unknown".to_string()); let paternal = design .paternal .as_ref() .map(|role| role.strain.clone()) .unwrap_or_else(|| "unknown".to_string()); let f1s: Vec = design.f1s.iter().map(|role| role.strain.clone()).collect(); if design.source == "metadata" { format!( "Parental design: {maternal} (maternal) x {paternal} (paternal){}; a \ mapping excludes the parents and F1s by default (see \ /groups/{name}/parents-and-f1s).", if f1s.is_empty() { String::new() } else { format!(", F1s {}", f1s.join(" / ")) } ) } else { format!( "Parental design: not recorded for this group, so a mapping can only \ drop individuals whose name contains `F1`; declare the parents in \ parents_and_f1s.json or exclude them with `individuals.exclude`." ) } }; Json( ctx.envelope(detail) .with_next( &format!("/groups/{name}/strains"), "The group's strains/samples", ) .with_next( &format!("/groups/{name}/case-attributes"), "Case-attribute names and per-strain values", ) .with_next( &format!("/groups/{name}/datasets"), "Expression (ProbeSet) datasets of the group", ) .with_next( &format!("/groups/{name}/traits"), "Published (phenotype) traits of the group (can be very large)", ) .with_next( &format!("/groups/{name}/genotypes"), "Genotype files this group can be mapped with, newest first", ) .with_next( &format!("/groups/{name}/parents-and-f1s"), "The family's parental design: parents, F1s, and what a mapping drops", ) .with_note(&design_note) .with_links(crate::suggest::root_links()), ) }) .ok_or_else(|| { ApiError::new( StatusCode::NOT_FOUND, "group_not_found", "Group not found", format!("No group matching '{not_found_name}'."), "group_by_name", ) .with_request_id(rid) .with_next("/groups") }) } #[derive(serde::Deserialize)] pub struct GroupStrainsParams { used_for_mapping: Option, } #[utoipa::path(get, path = "/groups/{group}/parents-and-f1s", summary = "A family's parental design: its parents, its F1s, and what a mapping drops", description = "The parental design of a family, from the deployment's \ `parents_and_f1s.json` (ported from GeneNetwork2's `ParInfo`): the F1 strains, \ the maternal and paternal strain, and -- when the metadata names them -- the \ individuals belonging to each role. It also says what the default mapping rule \ would drop from the group's current panel and which panel members the `F1` \ name heuristic catches, because an unlisted group's parents are invisible to \ that heuristic. `include_parents_f1` and `individuals` then decide what \ actually enters a mapping.", responses( (status = 200, description = "The design", body = Envelope), crate::error::Unauthorized, (status = 404, description = "No genotype file for that group", body = ApiError) ) )] #[gnauth(token_only)] pub async fn group_parental_design( ctx: Ctx, Path(group): Path, _token: AuthToken, ) -> Result>, ApiError> { let rid = ctx.request_info(); let config = Config::load(); let directory = std::path::PathBuf::from(&config.genotype_files_dir); let wanted = group.clone(); let design = tokio::task::spawn_blocking(move || { let resolved = genotypes::resolve(&directory, &wanted, None)?; let design = genotypes::file_meta(&resolved.geno) .ok() .and_then(|meta| { meta.labels .iter() .find(|(key, _)| key == "type") .map(|(_, value)| value.clone()) }); Ok::<_, genotypes::GenotypeError>(genotypes::parental_design( &directory, &wanted, Some(&resolved.panel), design, )) }) .await .map_err(|error| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", error.to_string(), "group_parental_design", ) .with_request_id(rid.clone()) })? .map_err(|error| { let (status, code, title) = match error { genotypes::GenotypeError::Invalid(_) => ( StatusCode::UNPROCESSABLE_ENTITY, "invalid_individuals", "Unusable individual selection", ), genotypes::GenotypeError::NotFound(_) => ( StatusCode::NOT_FOUND, "genotypes_not_found", "Genotype file not found", ), genotypes::GenotypeError::Io(_) => ( StatusCode::INTERNAL_SERVER_ERROR, "genotypes_unreadable", "Genotype files could not be read", ), }; ApiError::new(status, code, title, error.to_string(), "group_parental_design") .with_request_id(rid.clone()) })?; let mut envelope = ctx.envelope(design.clone()).with_note(&format!( "Roles come from {}. A mapping excludes the parents and F1s by default; \ `include_parents_f1: true` keeps them, and `individuals: {{\"include\": [...], \ \"exclude\": [...]}}` selects by name. Including them changes the *kinship* (GEMMA and \ R/qtl read no phenotypes for it), not the fit.", if design.source == "metadata" { "the deployment's parents_and_f1s.json" } else { "nothing -- this group is not listed, so only the `F1` name heuristic applies and the \ parents are unknown" } )); if !design.f1s.is_empty() && design.excluded_from_panel.is_empty() && !design.excluded_by_name.is_empty() { // The common case for an RI set: the metadata names the *design's* F1s // (B6D2F1), the panel carries *specific* intercross F1 individuals // (C57BL/6JxBXD037F1), so the metadata alone would exclude nothing and // the name heuristic does the work. envelope = envelope.with_note( "The F1 strains above describe the design; the panel's own F1 \ individuals have different names (an intercross F1 is named after its \ two parents, e.g. C57BL/6JxBXD037F1), so the exclusions come from the \ `F1` name rule here. `excluded_by_name` lists exactly which members \ that catches.", ); } if design.source != "metadata" { envelope = envelope.with_note( "This group has no parental metadata: any parent strain in its panel will be mapped \ as if it were a study individual. Add it to parents_and_f1s.json, or exclude it with \ `individuals.exclude`.", ); } Ok(Json(envelope.with_links(crate::suggest::root_links()))) } #[utoipa::path(get, path = "/groups/{group}/strains", summary = "List the strains/samples belonging to a group", params( ("group" = String, Path, description = "Group InbredSetName, Name, FullName or numeric Id"), ("used_for_mapping" = Option, Query, description = "Only strains/samples used for mapping") ), responses( (status = 200, description = "The strains/samples belonging to the group", body = Envelope>), Unauthorized, (status = 404, description = "No matching group", body = ApiError), (status = 500, description = "Database error", body = ApiError) ))] #[gnauth(token_only)] pub async fn group_strains( ctx: Ctx, Path(group): Path, Query(params): Query, _token: AuthToken, ) -> Result>>, ApiError> { let rid = ctx.request_info(); let not_found_name = group.clone(); let used_for_mapping = params.used_for_mapping; tokio::task::spawn_blocking(move || { db::get_group_by_name(&group).and_then(|group| match group { Some(group) => db::get_group_strains(group.id, used_for_mapping).map(Some), None => Ok(None), }) }) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "group_strains", ) .with_request_id(rid.clone()) })? .map_err(|e| ApiError::from_db(e, "group_strains").with_request_id(rid.clone()))? .map(|strains| { let group = path_segment(¬_found_name); Json( ctx.envelope(strains) .with_next( &format!("/groups/{group}"), "The group these strains belong to", ) .with_links(crate::suggest::group_links(¬_found_name)) .with_next( &format!("/groups/{group}/case-attributes"), "Case-attribute names and per-strain values", ), ) }) .ok_or_else(|| { ApiError::new( StatusCode::NOT_FOUND, "group_not_found", "Group not found", format!("No group matching '{not_found_name}'."), "group_strains", ) .with_request_id(rid) .with_next("/groups") }) } /// What looking up a trait within a group found, shared by /// group_trait_values and group_trait_info so each can tell a missing /// group from a missing trait and return the right 404. `Forbidden` /// mirrors src/routes/traits.rs and src/routes/datasets.rs: the same /// published (phenotype) data is reachable there via /// /traits/{dataset}/... with a gn-auth check, so it needs one here /// too (this was a known gap -- see docs/gn-auth.md). pub(crate) enum GroupTraitLookup { GroupNotFound, TraitNotFound, Forbidden, Found(Authorized, T), } /// Either a database error, or a failure to reach/parse gn-auth's /// answer while checking authorization for a non-public group. pub(crate) enum GroupAuthError { Db(db::DbError), Auth(String), } impl From for GroupAuthError { fn from(e: db::DbError) -> Self { GroupAuthError::Db(e) } } /// Resolve `group`'s PublishFreeze row and run the same /// public/confidentiality/create_time-gated gn-auth check /// src/routes/traits.rs applies when the same data is reached via /// /traits/{dataset}/... When a group has published traits /// (PublishXRef rows) with no PublishFreeze row to check -- not /// expected, but PublishXRef/PublishFreeze aren't tied by a foreign /// key -- this denies rather than treating ungated data as public. fn check_group_trait_authorized( group: &db::GroupDetail, trait_name: Option<&str>, auth_server_url: &str, token: &AuthToken, ) -> Result, GroupAuthError> { let Some(pf) = db::get_publish_freeze_by_name(&group.name)? else { return Ok(None); }; auth::check( auth_server_url, token, &pf.name, trait_name, pf.public, pf.confidentiality, &pf.create_time, ) .map_err(GroupAuthError::Auth) } pub(crate) fn get_group_trait_values_result( group: &str, trait_id: u32, auth_server_url: &str, token: &AuthToken, ) -> Result>, GroupAuthError> { let Some(group) = db::get_group_by_name(group)? else { return Ok(GroupTraitLookup::GroupNotFound); }; let values = db::get_group_trait_values(group.id, trait_id)?; if values.is_empty() { return Ok(GroupTraitLookup::TraitNotFound); } let trait_id_string = trait_id.to_string(); let Some(auth) = check_group_trait_authorized(&group, Some(&trait_id_string), auth_server_url, token)? else { return Ok(GroupTraitLookup::Forbidden); }; Ok(GroupTraitLookup::Found(auth, values)) } #[utoipa::path(get, path = "/groups/{group}/traits/{trait_id}/values", summary = "Get one published trait's value in each of a group's strains", params( ("group" = String, Path, description = "Group InbredSetName, Name, FullName or numeric Id"), ("trait_id" = u32, Path, description = "PublishXRef.Id of a published (phenotype) trait") ), responses( (status = 200, description = "The group's per-strain values for the trait", body = Envelope>), Unauthorized, (status = 403, description = "The trait's dataset isn't public, and the caller isn't authorized for it", body = ApiError), (status = 404, description = "No matching group, or no matching trait in that group", body = ApiError), (status = 500, description = "Database error", body = ApiError), (status = 502, description = "Could not reach gn-auth to check authorization", body = ApiError) ))] #[gnauth(secured)] pub async fn group_trait_values( ctx: Ctx, Path((group, trait_id)): Path<(String, u32)>, Query(normalize_params): Query, token: AuthToken, ) -> Result>>, ApiError> { let rid = ctx.request_info(); let pipeline = normalize_params .pipeline() .map_err(|detail| { ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "invalid_normalization", "Invalid normalization", detail, "group_trait_values", ) .with_request_id(rid.clone()) })?; let not_found_group = group.clone(); let auth_server_url = Config::load().auth_server_url.clone(); tokio::task::spawn_blocking(move || { get_group_trait_values_result(&group, trait_id, &auth_server_url, &token) }) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "group_trait_values", ) .with_request_id(rid.clone()) })? .map_err(|e| match e { GroupAuthError::Db(e) => { ApiError::from_db(e, "group_trait_values").with_request_id(rid.clone()) } GroupAuthError::Auth(e) => ApiError::new( StatusCode::BAD_GATEWAY, "auth_server_error", "Could not check authorization", e, "group_trait_values", ) .with_request_id(rid.clone()), }) .and_then(|lookup| match lookup { GroupTraitLookup::Found(authorized, values) => { let _: Authorized = authorized; let group = path_segment(¬_found_group); // Normalize after the values are read, over exactly the samples // this response returns: a caller who maps these numbers must get // the same population the z-scores or ranks were computed on. let mut values = values; let applied_note = if pipeline.is_identity() { None } else { let raw: Vec> = values.iter().map(|value| value.value).collect(); let (normalized, applied) = pipeline.apply(&raw).map_err(|detail| { ApiError::new( StatusCode::UNPROCESSABLE_ENTITY, "invalid_normalization", "Invalid normalization", detail, "group_trait_values", ) .with_request_id(rid.clone()) })?; for (value, normalized) in values.iter_mut().zip(normalized) { value.value = normalized; } Some(pipeline.describe(&applied)) }; let actions = suggest::mapping_actions_for_group_of( &values, &format!("{}::{trait_id}", not_found_group), Some(¬_found_group), Some(&pipeline), ); let mut envelope = ctx.envelope(values).with_actions(actions).with_next( &format!("/groups/{group}/traits/{trait_id}"), "The trait's metadata", ); envelope = envelope.with_links(crate::suggest::trait_links(¬_found_group, i64::from(trait_id))); if let Some(note) = &applied_note { envelope = envelope.with_note(note); } Ok(Json(envelope)) } GroupTraitLookup::Forbidden => Err(ApiError::new( StatusCode::FORBIDDEN, "forbidden", "Not authorized", format!( "Trait {trait_id} in group '{not_found_group}' is not public, \ and you are not authorized to view it." ), "group_trait_values", ) .with_request_id(rid.clone())), GroupTraitLookup::GroupNotFound => Err(ApiError::new( StatusCode::NOT_FOUND, "group_not_found", "Group not found", format!("No group matching '{not_found_group}'."), "group_trait_values", ) .with_request_id(rid.clone()) .with_next("/groups")), GroupTraitLookup::TraitNotFound => Err(ApiError::new( StatusCode::NOT_FOUND, "trait_not_found", "Trait not found", format!("No trait {trait_id} in group '{not_found_group}'."), "group_trait_values", ) .with_request_id(rid)), }) } fn get_group_trait_info_result( group: &str, trait_id: u32, auth_server_url: &str, token: &AuthToken, ) -> Result, GroupAuthError> { let Some(group) = db::get_group_by_name(group)? else { return Ok(GroupTraitLookup::GroupNotFound); }; let Some(info) = db::get_group_trait_info(group.id, trait_id)? else { return Ok(GroupTraitLookup::TraitNotFound); }; let trait_id_string = trait_id.to_string(); let Some(auth) = check_group_trait_authorized(&group, Some(&trait_id_string), auth_server_url, token)? else { return Ok(GroupTraitLookup::Forbidden); }; Ok(GroupTraitLookup::Found(auth, info)) } #[utoipa::path(get, path = "/groups/{group}/traits/{trait_id}", summary = "Get one published trait's PublishXRef/Phenotype/Publication metadata", params( ("group" = String, Path, description = "Group InbredSetName, Name, FullName or numeric Id"), ("trait_id" = u32, Path, description = "PublishXRef.Id of a published (phenotype) trait") ), responses( (status = 200, description = "The trait's PublishXRef/Phenotype/Publication metadata", body = Envelope), Unauthorized, (status = 403, description = "The trait's dataset isn't public, and the caller isn't authorized for it", body = ApiError), (status = 404, description = "No matching group, or no matching trait in that group", body = ApiError), (status = 500, description = "Database error", body = ApiError), (status = 502, description = "Could not reach gn-auth to check authorization", body = ApiError) ))] pub async fn group_trait_info( ctx: Ctx, Path((group, trait_id)): Path<(String, u32)>, token: AuthToken, ) -> Result>, ApiError> { let rid = ctx.request_info(); let not_found_group = group.clone(); let auth_server_url = Config::load().auth_server_url.clone(); tokio::task::spawn_blocking(move || { get_group_trait_info_result(&group, trait_id, &auth_server_url, &token) }) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "group_trait_info", ) .with_request_id(rid.clone()) })? .map_err(|e| match e { GroupAuthError::Db(e) => { ApiError::from_db(e, "group_trait_info").with_request_id(rid.clone()) } GroupAuthError::Auth(e) => ApiError::new( StatusCode::BAD_GATEWAY, "auth_server_error", "Could not check authorization", e, "group_trait_info", ) .with_request_id(rid.clone()), }) .and_then(|lookup| match lookup { GroupTraitLookup::Found(_authorized, info) => { let group = path_segment(¬_found_group); let pubmed_id = info.pubmed_id; let mut envelope = ctx .envelope(info) .with_note(db::LOD_NOTE) .with_next( &format!("/groups/{group}/traits/{trait_id}/values"), "The trait's value in each strain", ) .with_next( &format!("/groups/{group}"), "The group this trait belongs to", ) .with_links(crate::suggest::trait_links(¬_found_group, i64::from(trait_id))); if let Some(pubmed_id) = pubmed_id { envelope = envelope.with_next( &format!("/publications/{pubmed_id}/traits"), "Every trait reported by this trait's publication", ); } Ok(Json(envelope)) } GroupTraitLookup::Forbidden => Err(ApiError::new( StatusCode::FORBIDDEN, "forbidden", "Not authorized", format!( "Trait {trait_id} in group '{not_found_group}' is not public, \ and you are not authorized to view it." ), "group_trait_info", ) .with_request_id(rid.clone())), GroupTraitLookup::GroupNotFound => Err(ApiError::new( StatusCode::NOT_FOUND, "group_not_found", "Group not found", format!("No group matching '{not_found_group}'."), "group_trait_info", ) .with_request_id(rid.clone()) .with_next("/groups")), GroupTraitLookup::TraitNotFound => Err(ApiError::new( StatusCode::NOT_FOUND, "trait_not_found", "Trait not found", format!("No trait {trait_id} in group '{not_found_group}'."), "group_trait_info", ) .with_request_id(rid)), }) } /// Query parameters for `GET /groups/{group}/traits`. #[derive(Deserialize, utoipa::IntoParams)] pub struct GroupTraitsParams { /// Only the traits with this short name (abbreviation), e.g. /// "5HT_MB_M" or "3NP_Tox". pub abbreviation: Option, } enum GroupTraitsLookup { GroupNotFound, Forbidden, Found(Vec), } fn get_group_traits_result( group: &str, abbreviation: Option<&str>, auth_server_url: &str, token: &AuthToken, ) -> Result { let Some(group) = db::get_group_by_name(group)? else { return Ok(GroupTraitsLookup::GroupNotFound); }; let traits = match abbreviation { Some(abbreviation) => db::get_group_traits_by_abbreviation(group.id, abbreviation)?, None => db::get_group_traits(group.id)?, }; // Most groups have no published (phenotype) dataset at all -- // nothing here to protect, so don't spend a gn-auth round trip // (or deny) on an empty list. if traits.is_empty() { return Ok(GroupTraitsLookup::Found(traits)); } let Some(_auth) = check_group_trait_authorized(&group, None, auth_server_url, token)? else { return Ok(GroupTraitsLookup::Forbidden); }; Ok(GroupTraitsLookup::Found(traits)) } #[utoipa::path(get, path = "/groups/{group}/traits", summary = "List the published (phenotype) traits belonging to a group", params( ("group" = String, Path, description = "Group InbredSetName, Name, FullName or numeric Id"), GroupTraitsParams ), responses( (status = 200, description = "The published traits belonging to the group", body = Envelope>), Unauthorized, (status = 403, description = "The group's published data isn't public, and the caller isn't authorized for it", body = ApiError), (status = 404, description = "No matching group", body = ApiError), (status = 500, description = "Database error", body = ApiError), (status = 502, description = "Could not reach gn-auth to check authorization", body = ApiError) ))] pub async fn group_traits( ctx: Ctx, Path(group): Path, token: AuthToken, Query(params): Query, ) -> Result>>, ApiError> { let rid = ctx.request_info(); let not_found_name = group.clone(); let auth_server_url = Config::load().auth_server_url.clone(); tokio::task::spawn_blocking(move || { get_group_traits_result( &group, params.abbreviation.as_deref(), &auth_server_url, &token, ) }) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "group_traits", ) .with_request_id(rid.clone()) })? .map_err(|e| match e { GroupAuthError::Db(e) => ApiError::from_db(e, "group_traits").with_request_id(rid.clone()), GroupAuthError::Auth(e) => ApiError::new( StatusCode::BAD_GATEWAY, "auth_server_error", "Could not check authorization", e, "group_traits", ) .with_request_id(rid.clone()), }) .and_then(|lookup| match lookup { GroupTraitsLookup::Found(traits) => { let group = path_segment(¬_found_name); Ok(Json( ctx.envelope(traits) .with_note(db::LOD_NOTE) .with_links(crate::suggest::root_links()) .with_next( &format!("/groups/{group}"), "The group these traits belong to", ), )) } GroupTraitsLookup::Forbidden => Err(ApiError::new( StatusCode::FORBIDDEN, "forbidden", "Not authorized", format!( "Group '{not_found_name}' published data is not public, \ and you are not authorized to view it." ), "group_traits", ) .with_request_id(rid.clone())), GroupTraitsLookup::GroupNotFound => Err(ApiError::new( StatusCode::NOT_FOUND, "group_not_found", "Group not found", format!("No group matching '{not_found_name}'."), "group_traits", ) .with_request_id(rid) .with_next("/groups")), }) } #[utoipa::path(get, path = "/groups/{group}/case-attributes", summary = "Get a group's case attributes: defined attribute names and every strain's values", params( ("group" = String, Path, description = "Group InbredSetName, Name, FullName or numeric Id") ), responses( (status = 200, description = "The group's case-attribute names and per-strain values", body = Envelope), Unauthorized, (status = 404, description = "No matching group", body = ApiError), (status = 500, description = "Database error", body = ApiError) ))] #[gnauth(token_only)] pub async fn group_case_attributes( ctx: Ctx, Path(group): Path, _token: AuthToken, ) -> Result>, ApiError> { let rid = ctx.request_info(); let not_found_name = group.clone(); tokio::task::spawn_blocking(move || { db::get_group_by_name(&group).and_then(|group| match group { Some(group) => db::get_group_case_attributes(group.id).map(Some), None => Ok(None), }) }) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "group_case_attributes", ) .with_request_id(rid.clone()) })? .map_err(|e| ApiError::from_db(e, "group_case_attributes").with_request_id(rid.clone()))? .map(|case_attributes| { Json( ctx.envelope(case_attributes) .with_next( &format!("/groups/{}/strains", path_segment(¬_found_name)), "The group's strains/samples", ) .with_links(crate::suggest::group_links(¬_found_name)), ) }) .ok_or_else(|| { ApiError::new( StatusCode::NOT_FOUND, "group_not_found", "Group not found", format!("No group matching '{not_found_name}'."), "group_case_attributes", ) .with_request_id(rid) .with_next("/groups") }) } /// One case attribute's values for one trait: same samples, same order as /// that trait's values, so it can be used as a covariate without /// re-sorting. `/groups/{group}/traits/{id}/values` stays about trait /// values only. #[derive(Serialize, ToSchema)] pub struct TraitCaseAttributeValues { pub group: String, pub trait_id: u32, pub attribute: String, /// What the attribute means, as the database records it (`null` when /// it has no description). Read this before interpreting a name like /// `SeqCvge` or `Epoch`. #[serde(skip_serializing_if = "Option::is_none")] pub description: Option, /// One entry per sample of the trait, in the trait's own order; /// `value` is `null` where the sample has no value for the attribute. pub values: Vec, /// How often each value occurs, commonest first -- what tells you /// whether this attribute is usable as a covariate (a constant one is /// not). pub distinct: Vec, /// How many of the trait's samples have a value at all. pub num_values: usize, } /// One sample and its attribute text. #[derive(Serialize, ToSchema)] pub struct TraitCaseAttributeRow { pub name: String, #[serde(skip_serializing_if = "Option::is_none")] pub value: Option, } /// One distinct attribute value and its count. #[derive(Serialize, ToSchema)] pub struct CaseAttributeCount { pub value: String, pub count: usize, } #[utoipa::path(get, path = "/groups/{group}/traits/{trait_id}/case-attributes/{attribute}", summary = "One case attribute's values for one trait, in the trait's sample order", description = "Sex, age, tissue, batch -- the study's recorded metadata for exactly the samples a trait's values cover, in the same order, so it lines up with `/values` without re-sorting. The attribute's text is returned as recorded (`F`, `Live`, ...); `distinct` says how often each value occurs, which is what decides whether it is usable as a covariate.", params( ("group" = String, Path, description = "InbredSet name, e.g. BXD-Longevity"), ("trait_id" = u32, Path, description = "PublishXRef.Id within the group"), ("attribute" = String, Path, description = "CaseAttribute.Name, e.g. Sex") ), responses( (status = 200, description = "The attribute's values for the trait's samples", body = Envelope), Unauthorized, (status = 404, description = "No such group, trait, or attribute in that group", body = ApiError), (status = 500, description = "Database error", body = ApiError) ) )] #[gnauth(token_only)] pub async fn group_trait_case_attribute( ctx: Ctx, Path((group, trait_id, attribute)): Path<(String, u32, String)>, _token: AuthToken, ) -> Result>, ApiError> { let rid = ctx.request_info(); let link_group = group.clone(); let link_attribute = attribute.clone(); let attribute_for_query = attribute.clone(); tokio::task::spawn_blocking(move || { let Some(group_row) = db::get_group_by_name(&group)? else { return Ok(None); }; db::get_trait_case_attribute(group_row.id, trait_id, &attribute_for_query) .map(|found| found.map(|found| (group_row.name, found))) }) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "group_trait_case_attribute", ) .with_request_id(rid.clone()) })? .map_err(|e| ApiError::from_db(e, "group_trait_case_attribute").with_request_id(rid.clone()))? .map(|found| { let (group_name, found) = found; let values = found.values; let mut counts: std::collections::HashMap = std::collections::HashMap::new(); for row in &values { if let Some(value) = &row.value { *counts.entry(value.clone()).or_insert(0) += 1; } } let mut distinct: Vec = counts .into_iter() .map(|(value, count)| CaseAttributeCount { value, count }) .collect(); distinct.sort_by(|a, b| b.count.cmp(&a.count).then(a.value.cmp(&b.value))); let num_values = values.iter().filter(|row| row.value.is_some()).count(); let reply = TraitCaseAttributeValues { group: group_name, trait_id, attribute, description: found.description, values: values .into_iter() .map(|row| TraitCaseAttributeRow { name: row.name, value: row.value, }) .collect(), distinct, num_values, }; Json( ctx.envelope(reply) .with_note( "The attribute's values are text as recorded; converting them (F=1, M=0) \ is the caller's job. `distinct` counts them, so a constant attribute is \ visible before it is used as a covariate.", ) .with_next( &format!( "/groups/{}/traits/{}/values", path_segment(&link_group), trait_id ), "The trait's own values, in the same sample order", ) .with_next( &format!("/groups/{}/case-attributes", path_segment(&link_group)), "Every case attribute this group defines, with all values", ), ) }) .ok_or_else(|| { ApiError::new( StatusCode::NOT_FOUND, "not_found", "Not found", format!( "No group, trait or case attribute matching '{link_group}', {trait_id}, \ '{link_attribute}'." ), "group_trait_case_attribute", ) .with_request_id(rid) .with_next(&format!( "/groups/{}/case-attributes", path_segment(&link_group) )) }) } #[utoipa::path(get, path = "/groups/{group}/datasets", summary = "List the expression (ProbeSet) datasets belonging to a group", params( ("group" = String, Path, description = "Group InbredSetName, Name, FullName or numeric Id") ), responses( (status = 200, description = "The expression (ProbeSet) datasets belonging to the group", body = Envelope>), Unauthorized, (status = 404, description = "No matching group", body = ApiError), (status = 500, description = "Database error", body = ApiError) ))] #[gnauth(token_only)] pub async fn group_datasets( ctx: Ctx, Path(group): Path, _token: AuthToken, ) -> Result>>, ApiError> { let rid = ctx.request_info(); let not_found_name = group.clone(); tokio::task::spawn_blocking(move || { db::get_group_by_name(&group).and_then(|group| match group { Some(group) => db::get_group_datasets(group.id).map(Some), None => Ok(None), }) }) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "group_datasets", ) .with_request_id(rid.clone()) })? .map_err(|e| ApiError::from_db(e, "group_datasets").with_request_id(rid.clone()))? .map(|datasets| { // `next` links must be callable, so the probeset listing is offered // for a dataset that exists in this group rather than for the // `/datasets/{dataset}/probesets` template -- that is a shape, not an // address, and following it verbatim is a 404. let example = datasets.first().map(|dataset| { ( format!("/datasets/{}/probesets", path_segment(&dataset.name)), format!( "One dataset's probesets -- {} here; put any other name from \ the list in its place (can be very large)", dataset.name ), ) }); let mut envelope = ctx .envelope(datasets) .with_next( &format!("/groups/{}", path_segment(¬_found_name)), "The group these datasets belong to", ) .with_links(crate::suggest::group_links(¬_found_name)); if let Some((href, description)) = example { envelope = envelope.with_next(&href, &description); } Json(envelope) }) .ok_or_else(|| { ApiError::new( StatusCode::NOT_FOUND, "group_not_found", "Group not found", format!("No group matching '{not_found_name}'."), "group_datasets", ) .with_request_id(rid) .with_next("/groups") }) }