about summary refs log tree commit diff
path: root/src
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-11 15:15:40 +0000
committerPjotr <wrk@bosa.lan>2026-11-11 15:15:40 +0000
commitee007a3731d186dc12c1b8b81589a03e8eb95acb (patch)
treee3bd07ae86d5219ba73530dc62a94b46e4c12f15 /src
parent22e2d8fedcba427f15859ecd1b1cb79c3aefd59c (diff)
downloadgenenetwork4-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.rs9
-rw-r--r--src/wikidata.rs199
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
+}