Add parents for implicitly declared classes (#488)

Motivated by biopragmatics/bioregistry#1811,
follow-up to #486.

This PR adds a function that can be used to search all terms in an
ontology, identify external references that weren't explicitly declared
as a class in the ontology, and add a declaration.

All terms declared this way get put under an ontology-wide _ad hoc_
grouping term, which in turn has children corresponding to each prefix
for which undeclared classes were found.

For example, in HGNC, the ontology-wide grouping term is
http://purl.obolibrary.org/obo/hgnc#aux, under which are terms like
http://purl.obolibrary.org/obo/hgnc#aux-ec (fo

Here's how it looks for HGNC:

<img width="1019" height="961" alt="Screenshot 2026-02-22 at 17 30 02"
src="https://github.com/user-attachments/assets/77592273-eb81-45ca-bd73-951ddb471d1c"
/>

There are a few caveats to this approach:

1. Axiom injection (🤷)
2. Doesn't get nice metadata like labels
3. Weird looking labels because there are no labels (will be improved
with protegeproject/protege#1322)

Author: cthoyt

src/pyobo/sources/hgnc/hgnc.py

@@ -16,7 +16,13 @@
 from pyobo.resources.so import get_so_name
 from pyobo.sources.hgnc.hgncgenefamily import GENE_GROUP_PREFIX, get_gene_family_terms
 from pyobo.struct import Annotation, Obo, OBOLiteral, Reference, Term
-from pyobo.struct.struct import gene_symbol_synonym, previous_gene_symbol, previous_name
+from pyobo.struct import vocabulary as v
+from pyobo.struct.struct import (
+    cleanup_terms,
+    gene_symbol_synonym,
+    previous_gene_symbol,
+    previous_name,
+)
 from pyobo.struct.typedef import (
     comment,
     enables,
@@ -222,7 +228,22 @@ class HGNCGetter(Obo):
 
     def iter_terms(self, force: bool = False) -> Iterable[Term]:
         """Iterate over terms in the ontology."""
-        return get_terms(force=force, version=self.data_version)
+        yield from cleanup_terms(
+            get_terms(force=force, version=self.data_version),
+            prefix=PREFIX,
+            prefix_allowlist={
+                "chr": v.chromosomal_region,
+                "uniprot": v.protein,
+                "mgi": v.gene,
+                "rgd": v.gene,
+                "go": v.molecular_function,
+                "ec": v.molecular_function,
+                "ncbigene": v.gene,
+                "rnacentral": v.rna,
+                "mirbase": v.rna,
+                "snornabase": v.rna,
+            },
+        )
 
 
 def _get_location_to_chr() -> dict[str, Reference]:

src/pyobo/sources/hgnc/hgncgenefamily.py

@@ -9,11 +9,10 @@
 from ...struct.struct import Obo, Reference, Term
 from ...struct.struct import abbreviation as symbol_type
 from ...struct.typedef import enables, exact_match, from_species, is_mentioned_by
+from ...struct.vocabulary import GENE_GROUP
 from ...utils.path import ensure_df
 
 __all__ = [
-    "GENE_GROUP_REFERENCE",
-    "GENE_GROUP_TERM",
     "HGNCGroupGetter",
     "get_gene_family_terms",
 ]
@@ -30,6 +29,7 @@ class HGNCGroupGetter(Obo):
     ontology = GENE_GROUP_PREFIX
     bioversions_key = "hgnc"
     synonym_typedefs = [symbol_type]
+    root_terms = [GENE_GROUP]
     typedefs = [from_species, enables, exact_match, is_mentioned_by]
 
     def iter_terms(self, force: bool = False) -> Iterable[Term]:
@@ -50,9 +50,6 @@ def get_hierarchy(*, version: str | None = None, force: bool = False) -> Mapping
 
 COLUMNS = ["id", "abbreviation", "name", "pubmed_ids", "desc_comment", "desc_go"]
 
-GENE_GROUP_REFERENCE = Reference(prefix="SO", identifier="0005855", name="gene group")
-GENE_GROUP_TERM = Term(reference=GENE_GROUP_REFERENCE)
-
 
 def get_gene_family_terms(*, version: str | None = None, force: bool = False) -> Iterable[Term]:
     """Get the HGNC Gene Group terms."""
@@ -67,10 +64,10 @@ def get_gene_family_terms(*, version: str | None = None, force: bool = False) ->
         child: Term = id_to_term[child_id]
         for parent_id in parent_ids:
             child.append_parent(id_to_term[parent_id])
-    yield GENE_GROUP_TERM
+    yield Term(reference=GENE_GROUP)
     for term in terms:
         if not term.parents:
-            term.append_parent(GENE_GROUP_REFERENCE)
+            term.append_parent(GENE_GROUP)
     yield from terms
 
 

src/pyobo/struct/struct.py

@@ -2527,3 +2527,43 @@ def iter_terms(self, force: bool = False) -> Iterable[Term]:
 HUMAN_TERM = Term(reference=v.HUMAN)
 CHARLIE_TERM = Term(reference=v.CHARLIE, type="Instance").append_parent(HUMAN_TERM)
 PYOBO_INJECTED = "Injected by PyOBO"
+
+
+def cleanup_terms(
+    terms: Iterable[Term], *, prefix: str, prefix_allowlist: dict[str, Reference]
+) -> set[Term]:
+    """Define missing references as classes."""
+    aux_term = Term(reference=default_reference(prefix, "aux", "auxiliary terms"))
+
+    terms = set(terms)
+    term_references: dict[Reference, Term] = {term.reference: term for term in terms}
+
+    prefix_to_parent_term: dict[str, Term] = {}
+    for allowlist_prefix, allowlist_reference in prefix_allowlist.items():
+        if allowlist_reference not in term_references:
+            term = Term(reference=allowlist_reference)
+            term_references[allowlist_reference] = term
+            prefix_to_parent_term[allowlist_prefix] = term
+            terms.add(term)
+
+        prefix_to_parent_term[allowlist_prefix] = (
+            Term.default(
+                allowlist_prefix,
+                f"aux-{allowlist_prefix}",
+                name=f"auxiliary terms from {allowlist_prefix}",
+            )
+            .append_parent(aux_term)
+            .append_parent(allowlist_reference)
+        )
+
+    undefined: dict[Reference, Term] = {}
+    for term in terms:
+        for references in term._get_references().values():
+            for reference in references:
+                if reference in term_references or reference in undefined:
+                    continue
+                if parent := prefix_to_parent_term.get(reference.prefix):
+                    undefined[reference] = Term(reference=reference).append_parent(parent)
+
+    rv = terms | {aux_term} | set(prefix_to_parent_term.values()) | set(undefined.values())
+    return rv

src/pyobo/struct/vocabulary.py

@@ -154,3 +154,12 @@ def _c(c: curies.Reference) -> Reference:
     comment,  # maps to "comment:" line with strings
     obo_creation_date,
 ]
+
+mouse = Reference(prefix="NCBITaxon", identifier="10090", name="Mus musculus")
+rat = Reference(prefix="NCBITaxon", identifier="10116", name="Rattus norvegicus")
+gene = Reference(prefix="SO", identifier="0000704", name="gene")
+GENE_GROUP = Reference(prefix="SO", identifier="0005855", name="gene group")
+protein = Reference(prefix="PR", identifier="000000001", name="protein")
+molecular_function = Reference(prefix="GO", identifier="0003674", name="molecular function")
+rna = Reference(prefix="uniprot.core", identifier="RNA", name="RNA")
+chromosomal_region = Reference(prefix="GO", identifier="0098687", name="chromosomal region")