diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-11 15:15:40 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-11 15:15:40 +0000 |
| commit | ee007a3731d186dc12c1b8b81589a03e8eb95acb (patch) | |
| tree | e3bd07ae86d5219ba73530dc62a94b46e4c12f15 /src | |
| parent | 22e2d8fedcba427f15859ecd1b1cb79c3aefd59c (diff) | |
| download | genenetwork4-ee007a3731d186dc12c1b8b81589a03e8eb95acb.tar.gz | |
genes: the alias reply carries the entity's label and its gene link-outs
The GTEx problem -- it is human-only, and a mouse symbol there is an empty
report -- is answered by the endpoint that already knows which entity it
matched: /genes/{symbol}/aliases now returns
label the entity's canonical symbol in that species ("Shh" for mouse,
"SHH" for ?species=human) -- the symbol a human-only service needs
links [{name, href, description}] built for that symbol and species:
RGD, MGI, BioAlliance, NCBI Gene, Wikidata (the QID), UniProt,
STRING, GeneMANIA and GeneCup, plus GTEx/Open Targets/Protein
Atlas/GWAS Catalog for a human entity or BioGPS/Allen Brain Atlas
for a mouse one
So a mouse Shh reaches GTEx through the human ortholog's label rather than a
guessed one, and a client no longer holds the URL vocabulary. Only links
that answer are built: HomoloGene, UniGene, Genotation, GeneBridge and
PhenoGen are gone, and Panther is browser-only (see SKILL.md "Gene
link-outs", where each URL was checked).
A cached entity written before the label was kept is refreshed rather than
served -- otherwise the link-outs would be built on a symbol it does not
have -- and `stale: true` still says when Wikidata was unreachable and the
cached answer was used.
tests/wikidata.rs: a mouse gene gets the mouse services and no GTEx; the
human ortholog gets label SHH and a GTEx href built from it. Both halves
skip when the reply is stale, since a Wikidata timeout is not a failure.
Diffstat (limited to 'src')
| -rw-r--r-- | src/routes/probesets.rs | 9 | ||||
| -rw-r--r-- | src/wikidata.rs | 199 |
2 files changed, 206 insertions, 2 deletions
diff --git a/src/routes/probesets.rs b/src/routes/probesets.rs index e6e4154..f824abe 100644 --- a/src/routes/probesets.rs +++ b/src/routes/probesets.rs @@ -461,6 +461,15 @@ pub async fn gene_aliases( .with_request_id(rid.clone()), })?; let age_hours = (chrono_now() - answer.fetched_at).max(0) as f64 / 3600.0; + // Where else to send a reader about this gene, keyed on the symbol and + // species that were matched (GTEx only for a human entity: it is human-only). + let mut answer = answer.clone(); + answer.links = wikidata::link_outs( + &answer.symbol, + answer.species.as_deref(), + answer.label.as_deref(), + answer.wikidata_id.as_deref(), + ); let mut envelope = ctx .envelope(answer.clone()) .with_note(&format!( diff --git a/src/wikidata.rs b/src/wikidata.rs index f5f75a2..b2349e7 100644 --- a/src/wikidata.rs +++ b/src/wikidata.rs @@ -49,12 +49,34 @@ pub struct GeneAliases { /// Which of human/mouse/rat it matched, when the request did not say. #[serde(skip_serializing_if = "Option::is_none")] pub species: Option<String>, + /// The entity's own `rdfs:label` in that species -- the canonical symbol, + /// which is what a service keyed on the human symbol needs when the caller + /// asked for `?species=human` (a mouse `Shh` gives `SHH`). + #[serde(skip_serializing_if = "Option::is_none")] + pub label: Option<String>, /// `skos:altLabel`s, sorted, the symbol itself removed. pub aliases: Vec<String>, /// When Wikidata last answered, in Unix seconds. pub fetched_at: i64, /// True when Wikidata could not be reached and this is the cached answer. pub stale: bool, + /// Where else to send a reader about this gene: the services GeneNetwork2's + /// trait page links to, keyed on the symbol and species that were actually + /// matched. GTEx appears only for a human entity, because it is human-only + /// and a mouse symbol there is an empty report -- ask `?species=human` for + /// the ortholog's label when you need that link. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub links: Vec<GeneLink>, +} + +/// One external gene page. +#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, utoipa::ToSchema)] +pub struct GeneLink { + /// The service, e.g. "RGD". + pub name: String, + pub href: String, + /// What it is for, in one sentence. + pub description: String, } /// What is stored in LMDB: the answer without the per-request flags. @@ -63,6 +85,8 @@ pub struct Stored { pub symbol: String, pub wikidata_id: Option<String>, pub species: Option<String>, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub label: Option<String>, pub aliases: Vec<String>, pub fetched_at: i64, } @@ -119,7 +143,7 @@ pub fn gene_id_query(symbol: &str, species: Option<&str>) -> String { }; let values: Vec<String> = taxa.iter().map(|qid| format!("(wd:{qid})")).collect(); format!( - "SELECT DISTINCT ?wikidata_id ?species WHERE {{\n \ + "SELECT DISTINCT ?wikidata_id ?species ?label WHERE {{\n \ ?wikidata_id wdt:P31 wd:Q7187 ;\n wdt:P703 ?species ;\n \ rdfs:label ?label .\n \ VALUES (?species) {{ {} }}\n \ @@ -182,6 +206,7 @@ fn fetch( }) .collect(); let species_rows = binding_values(&ids, "species"); + let label_rows = binding_values(&ids, "label"); let mut entities: Vec<(String, Option<String>)> = rows .into_iter() .enumerate() @@ -208,10 +233,12 @@ fn fetch( symbol: symbol.to_string(), wikidata_id: None, species: species.map(str::to_string), + label: None, aliases: Vec::new(), fetched_at: now(), }); }; + let label = label_rows.first().cloned(); let alias_body = sparql(endpoint, &aliases_query(&wikidata_id))?; let mut aliases: Vec<String> = binding_values(&alias_body, "alias"); aliases.retain(|alias| !alias.eq_ignore_ascii_case(symbol) && !alias.trim().is_empty()); @@ -221,6 +248,7 @@ fn fetch( symbol: symbol.to_string(), wikidata_id: Some(wikidata_id), species: found_species, + label, aliases, fetched_at: now(), }) @@ -320,14 +348,18 @@ pub fn lookup( let key = key(symbol, species); let previous = cached(file, &key).unwrap_or(None); if let Some(previous) = &previous { - if !refresh && is_fresh(previous, ttl, now()) { + // An entry written before the label was kept is incomplete: refetch it + // rather than serve a reply whose link-outs would use the wrong symbol. + if !refresh && previous.label.is_some() && is_fresh(previous, ttl, now()) { return Ok(GeneAliases { symbol: previous.symbol.clone(), wikidata_id: previous.wikidata_id.clone(), species: previous.species.clone(), + label: previous.label.clone(), aliases: previous.aliases.clone(), fetched_at: previous.fetched_at, stale: false, + links: Vec::new(), }); } } @@ -340,9 +372,11 @@ pub fn lookup( symbol: fresh.symbol, wikidata_id: fresh.wikidata_id, species: fresh.species, + label: fresh.label, aliases: fresh.aliases, fetched_at: fresh.fetched_at, stale: false, + links: Vec::new(), }) } Err(error) => match previous { @@ -350,9 +384,11 @@ pub fn lookup( symbol: previous.symbol, wikidata_id: previous.wikidata_id, species: previous.species, + label: previous.label, aliases: previous.aliases, fetched_at: previous.fetched_at, stale: true, + links: Vec::new(), }), None => Err(error), }, @@ -381,6 +417,7 @@ mod tests { symbol: "Shh".to_string(), wikidata_id: Some("Q24420953".to_string()), species: Some("rat".to_string()), + label: Some("Shh".to_string()), aliases: vec!["HHG1".to_string()], fetched_at: 1_000_000, }; @@ -440,6 +477,7 @@ mod tests { symbol: "Shh".to_string(), wikidata_id: Some("Q24420953".to_string()), species: Some("rat".to_string()), + label: Some("Shh".to_string()), aliases: vec!["HHG1".to_string(), "TPT".to_string()], fetched_at: 1_700_000_000, }; @@ -466,6 +504,7 @@ mod tests { symbol: "Shh".to_string(), wikidata_id: Some("Q24420953".to_string()), species: Some("rat".to_string()), + label: Some("Shh".to_string()), aliases: vec!["HHG1".to_string()], // Long expired, so the refresh is attempted. fetched_at: 1_600_000_000, @@ -495,3 +534,159 @@ mod tests { } } } + +/// Percent-encode a symbol for a URL component. Gene symbols are mostly +/// alphanumeric and hyphenated; the exception is worth handling rather than +/// pasting into a link unescaped. +fn encode(text: &str) -> String { + let mut out = String::with_capacity(text.len()); + for byte in text.bytes() { + if byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b'~') { + out.push(byte as char); + } else { + out.push_str(&format!("%{byte:02X}")); + } + } + out +} + +/// The taxon id for a species name, for the services that want one. +fn taxon(species: Option<&str>) -> Option<&'static str> { + match species { + Some(name) if name.eq_ignore_ascii_case("mouse") => Some("10090"), + Some(name) if name.eq_ignore_ascii_case("rat") => Some("10116"), + Some(name) if name.eq_ignore_ascii_case("human") => Some("9606"), + _ => None, + } +} + +/// The external gene pages for a matched entity: what GeneNetwork2's trait page +/// offers, restricted to the ones that answer (see SKILL.md, "Gene link-outs"). +/// The symbol used is the entity's own label when there is one -- a mouse `Shh` +/// asked for as `?species=human` gives `SHH`, which is what GTEx needs. +pub fn link_outs(symbol: &str, species: Option<&str>, label: Option<&str>, qid: Option<&str>) -> Vec<GeneLink> { + let name = label.unwrap_or(symbol); + let encoded = encode(name); + let species_name = species.unwrap_or("mouse"); + let rgd_species = match species_name.to_lowercase().as_str() { + "rat" => "Rat", + "human" => "Human", + _ => "Mouse", + }; + let mut links = Vec::new(); + let push = |links: &mut Vec<GeneLink>, name: &str, href: String, description: &str| { + links.push(GeneLink { + name: name.to_string(), + href, + description: description.to_string(), + }) + }; + if let Some(qid) = qid { + push( + &mut links, + "Wikidata", + format!("https://www.wikidata.org/wiki/{}", encode(qid)), + "Identifiers, aliases and cross-references for the gene entity", + ); + } + push( + &mut links, + "RGD", + format!( + "https://rgd.mcw.edu/rgdweb/elasticResults.html?term={encoded}&category=Gene&species={rgd_species}" + ), + "Orthologs, phenotypes, expression and QTLs (mouse and rat)", + ); + if species_name.eq_ignore_ascii_case("mouse") { + push( + &mut links, + "MGI", + format!("https://www.informatics.jax.org/searchtool/SearchResults?query={encoded}"), + "Mouse gene authority: alleles, knockouts, phenotypes", + ); + push( + &mut links, + "BioGPS", + format!("http://biogps.org/?org=10090#goto=genereport&id={encoded}"), + "Mouse expression across tissues and datasets", + ); + push( + &mut links, + "Allen Brain Atlas", + format!("https://mouse.brain-map.org/search/show?search_type=gene&search_term={encoded}"), + "In-situ hybridisation in mouse brain", + ); + } + push( + &mut links, + "Alliance of Genome Resources", + format!("https://www.alliancegenome.org/search?category=gene&q={encoded}"), + "Cross-species reference: orthologs and disease models", + ); + let organism = match species_name.to_lowercase().as_str() { + "rat" => "rat", + "human" => "human", + _ => "mouse", + }; + push( + &mut links, + "NCBI Gene", + format!("https://www.ncbi.nlm.nih.gov/gene/?term={encoded}%5Bgene%5D%20AND%20{organism}%5Borgn%5D"), + "The canonical gene record", + ); + if let Some(taxon) = taxon(species) { + push( + &mut links, + "UniProt", + format!( + "https://www.uniprot.org/uniprotkb?query=gene%3A{encoded}%20AND%20organism_id%3A{taxon}" + ), + "Protein entry, domains and variants", + ); + push( + &mut links, + "STRING", + format!("https://string-db.org/cgi/network?identifier={encoded}&species={taxon}"), + "Protein-protein interaction network", + ); + } + push( + &mut links, + "GeneMANIA", + format!("https://genemania.org/search/{}/{encoded}", species_name.to_lowercase()), + "Functional association network", + ); + if species_name.eq_ignore_ascii_case("human") { + push( + &mut links, + "GTEx", + format!("https://www.gtexportal.org/home/gene/{encoded}"), + "Human tissue expression (this link needs the human symbol -- ?species=human)", + ); + push( + &mut links, + "Open Targets", + format!("https://platform.opentargets.org/search?q={encoded}"), + "Target-disease associations", + ); + push( + &mut links, + "Human Protein Atlas", + format!("https://www.proteinatlas.org/search/{encoded}"), + "Protein-level expression across human tissues", + ); + push( + &mut links, + "GWAS Catalog", + format!("https://www.ebi.ac.uk/gwas/search?query={encoded}"), + "Published GWAS associations", + ); + } + push( + &mut links, + "GeneCup", + format!("https://genecup.org/progress?type=GWAS&query={encoded}"), + "Literature-mined gene-disease links", + ); + links +} |
