feat: fetch ontology term descriptions, if available (#181)

api/python/src/cellxgene_ontology_guide/ontology_parser.py

@@ -473,3 +473,37 @@ def map_term_labels(self, term_ids: Iterable[str]) -> Dict[str, str]:
         :return: Dict[str, str] mapping term IDs to their respective human-readable labels
         """
         return {term_id: self.get_term_label(term_id) for term_id in term_ids}
+
+    def get_term_description(self, term_id: str) -> Optional[str]:
+        """
+        Fetch the description for a given ontology term.
+
+        Example
+        >>> from cellxgene_ontology_guide.ontology_parser import OntologyParser
+        >>> ontology_parser = OntologyParser()
+        >>> ontology_parser.get_term_description("CL:0000005")
+        'Any fibroblast that is deriived from the neural crest.'
+
+        :param term_id: str ontology term to fetch description for
+        :return: str description for the term
+        """
+        if term_id in VALID_NON_ONTOLOGY_TERMS:
+            return term_id
+        ontology_name = self._parse_ontology_name(term_id)
+        description: Optional[str] = self.cxg_schema.ontology(ontology_name)[term_id].get("description", None)
+        return description
+
+    def map_term_descriptions(self, term_ids: List[str]) -> Dict[str, Optional[str]]:
+        """
+        Fetch the descriptions for a given list of ontology terms.
+
+        Example
+        >>> from cellxgene_ontology_guide.ontology_parser import OntologyParser
+        >>> ontology_parser = OntologyParser()
+        >>> ontology_parser.map_term_descriptions(["CL:0000005", "CL:0000006"])
+        {'CL:0000005': 'Any fibroblast that is deriived from the neural crest.', 'CL:0000006': None}
+
+        :param term_ids: list of str ontology terms to fetch descriptions for
+        :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}

api/python/tests/test_ontology_parser.py

@@ -8,7 +8,7 @@
 @pytest.fixture
 def ontology_dict():
     return {
-        "CL:0000000": {"ancestors": {}, "label": "cell A", "deprecated": False},
+        "CL:0000000": {"ancestors": {}, "label": "cell A", "description": "This is cell A.", "deprecated": False},
         "CL:0000001": {
             "ancestors": {"CL:0000000": 1},
             "label": "cell B",
@@ -221,6 +221,19 @@ def test_map_term_labels(ontology_parser):
     }
 
 
+def test_get_term_description(ontology_parser):
+    assert ontology_parser.get_term_description("CL:0000000") == "This is cell A."
+
+
+def test_map_term_description(ontology_parser):
+    assert ontology_parser.map_term_descriptions(["CL:0000000", "CL:0000004", "unknown", "na"]) == {
+        "CL:0000000": "This is cell A.",
+        "CL:0000004": None,
+        "unknown": "unknown",
+        "na": "na",
+    }
+
+
 def test_get_high_level_terms(ontology_parser):
     high_level_terms = ["CL:0000000", "CL:0000001"]
     assert ontology_parser.get_high_level_terms("CL:0000004", high_level_terms) == ["CL:0000000", "CL:0000001"]

artifact-schemas/all_ontology_schema.json

@@ -13,6 +13,10 @@
         "type": "string",
         "description": "human-readable name for the ontology entry."
       },
+      "description": {
+        "type": "string",
+        "description": "Optional description of the ontology entry."
+      },
       "deprecated": {
         "type": "boolean",
         "description": "Indicates whether the ontology entry is deprecated."

ontology-assets/ontology_info.json

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

tools/ontology-builder/src/all_ontology_generator.py

@@ -193,9 +193,12 @@ def _extract_ontology_term_metadata(onto: owlready2.entity.ThingClass) -> Dict[s
         # no current use-case for NCBITaxon
         term_dict[term_id]["ancestors"] = {} if onto.name == "NCBITaxon" else ancestors
 
-        # Gets label
         term_dict[term_id]["label"] = onto_term.label[0] if onto_term.label else ""
 
+        # optional description, if available
+        if getattr(onto_term, "IAO_0000115", None):
+            term_dict[term_id]["description"] = onto_term.IAO_0000115[0]
+
         # Add the "deprecated" status and associated metadata if True
         term_dict[term_id]["deprecated"] = False
         if onto_term.deprecated and onto_term.deprecated.first():