feat: fetch ontology term synonyms (#200)

api/python/ontology-assets-version.txt

@@ -1 +1 @@
-da5ad20b326bd7e5c5ae2569cab3aa70d38e2a0e
+22dd42053d936b87d05c9786328723226e36c84e

api/python/src/cellxgene_ontology_guide/ontology_parser.py

@@ -562,3 +562,39 @@ def map_term_descriptions(self, term_ids: List[str]) -> Dict[str, Optional[str]]
         :return: Dict[str, str] mapping term IDs to their respective descriptions
         """
         return {term_id: self.get_term_description(term_id) for term_id in term_ids}
+
+    def get_term_synonyms(self, term_id: str) -> List[str]:
+        """
+        Fetch a list of synonym labels for a given ontology term. Returns empty list if no synonyms found.
+        Raises ValueError if term ID is not valid member of a supported ontology.
+
+        Example
+        >>> from cellxgene_ontology_guide.ontology_parser import OntologyParser
+        >>> ontology_parser = OntologyParser()
+        >>> ontology_parser.get_term_synonyms("CL:0000019")
+        ['sperm cell', 'spermatozoid', 'spermatozoon']
+
+        :param term_id: str ontology term to fetch synonyms for
+        :return: List[str] synonyms for the term
+        """
+        if term_id in VALID_NON_ONTOLOGY_TERMS:
+            return []
+        ontology_name = self._parse_ontology_name(term_id)
+        synonyms: List[str] = self.cxg_schema.ontology(ontology_name)[term_id].get("synonyms", [])
+        return synonyms
+
+    def map_term_synonyms(self, term_ids: List[str]) -> Dict[str, List[str]]:
+        """
+        Fetch the synonym labels for a given list of ontology terms. Raises ValueError if term ID is not valid member of
+        a supported ontology.
+
+        Example
+        >>> from cellxgene_ontology_guide.ontology_parser import OntologyParser
+        >>> ontology_parser = OntologyParser()
+        >>> ontology_parser.map_term_synonyms(["CL:0000005", "CL:0000019"])
+        {'CL:0000005': [], 'CL:0000019': ['sperm cell', 'spermatozoid', 'spermatozoon']}
+
+        :param term_ids: list of str ontology terms to fetch synonyms for
+        :return: Dict[str, List[str]] mapping term IDs to their respective synonym lists
+        """
+        return {term_id: self.get_term_synonyms(term_id) for term_id in term_ids}

api/python/tests/test_ontology_parser.py

@@ -14,6 +14,7 @@ def ontology_dict():
             "label": "cell B",
             "deprecated": False,
             "consider": ["CL:0000004"],
+            "synonyms": ["cell Beta", "cell Bravo"],
         },
         "CL:0000002": {"ancestors": {"CL:0000000": 1}, "label": "cell C", "deprecated": False},
         "CL:0000003": {
@@ -232,6 +233,19 @@ def test_map_term_description(ontology_parser):
     }
 
 
+def test_get_term_synonyms(ontology_parser):
+    assert ontology_parser.get_term_synonyms("CL:0000001") == ["cell Beta", "cell Bravo"]
+
+
+def test_map_term_synonyms(ontology_parser):
+    assert ontology_parser.map_term_synonyms(["CL:0000000", "CL:0000001", "unknown", "na"]) == {
+        "CL:0000000": [],
+        "CL:0000001": ["cell Beta", "cell Bravo"],
+        "unknown": [],
+        "na": [],
+    }
+
+
 @pytest.mark.parametrize(
     "term_id,high_level_terms,expected",
     [

asset-schemas/all_ontology_schema.json

@@ -56,6 +56,14 @@
         "type": "string",
         "pattern": "^\\w+:\\w+$",
         "description": "If deprecated, the ID of the ontology entry that should canonically replace this one."
+      },
+      "synonyms": {
+          "type": "array",
+          "items": {
+          "type": "string"
+          },
+          "minItems": 0,
+          "description": "Optional list of synonym labels for the ontology entry."
       }
     },
     "required": [

ontology-assets/ontology_info.json

@@ -48,4 +48,4 @@
       }
     }
   }
-}
+}

tools/ontology-builder/src/all_ontology_generator.py

@@ -194,6 +194,9 @@ def _extract_ontology_term_metadata(onto: owlready2.entity.ThingClass) -> Dict[s
         # optional description, if available
         if getattr(onto_term, "IAO_0000115", None):
             term_dict[term_id]["description"] = onto_term.IAO_0000115[0]
+        # optional synonym list, if available
+        if getattr(onto_term, "hasExactSynonym", None):
+            term_dict[term_id]["synonyms"] = onto_term.hasExactSynonym
 
         # Add the "deprecated" status and associated metadata if True
         term_dict[term_id]["deprecated"] = False