pyobo 0.12.1__py3-none-any.whl → 0.12.3__py3-none-any.whl

pyobo/struct/obograph/export.py

@@ -0,0 +1,315 @@
+"""Exports to OBO Graph JSON."""
+
+import tempfile
+from pathlib import Path
+
+import bioregistry
+import curies
+import obographs as og
+from curies import Converter, ReferenceTuple
+from curies import vocabulary as v
+
+from pyobo.identifier_utils.api import get_converter
+from pyobo.struct import Obo, OBOLiteral, Stanza, Term, TypeDef
+from pyobo.struct import typedef as tdv
+from pyobo.utils.io import safe_open
+
+__all__ = [
+    "to_obograph",
+    "to_parsed_obograph",
+    "write_obograph",
+]
+
+
+def write_obograph(obo: Obo, path: str | Path, *, converter: Converter | None = None) -> None:
+    """Write an ontology to a file as OBO Graph JSON."""
+    path = Path(path).expanduser().resolve()
+    raw_graph = to_obograph(obo, converter=converter)
+    with safe_open(path, read=False) as file:
+        file.write(raw_graph.model_dump_json(indent=2, exclude_none=True, exclude_unset=True))
+
+
+def to_parsed_obograph_oracle(
+    obo: Obo, *, converter: Converter | None = None
+) -> og.StandardizedGraphDocument:
+    """Serialize to OBO, convert to OBO Graph JSON with ROBOT, load, then parse."""
+    import bioontologies.robot
+
+    if converter is None:
+        converter = get_converter()
+
+    with tempfile.TemporaryDirectory() as directory:
+        stub = Path(directory).joinpath("test")
+        obo_path = stub.with_suffix(".obo")
+        obograph_path = stub.with_suffix(".json")
+        obo.write_obo(obo_path)
+        bioontologies.robot.convert(input_path=obo_path, output_path=obograph_path)
+        raw = og.read(obograph_path, squeeze=False)
+    rv = raw.standardize(converter)
+    for graph in rv.graphs:
+        if graph.meta and graph.meta.properties:
+            graph.meta.properties = [
+                p
+                for p in graph.meta.properties
+                if p.predicate.pair
+                != ReferenceTuple(prefix="oboinowl", identifier="hasOBOFormatVersion")
+            ] or None
+    return rv
+
+
+def to_obograph(obo: Obo, *, converter: Converter | None = None) -> og.GraphDocument:
+    """Convert an ontology to a OBO Graph JSON document."""
+    if converter is None:
+        converter = get_converter()
+    return to_parsed_obograph(obo).to_raw(converter)
+
+
+def to_parsed_obograph(obo: Obo) -> og.StandardizedGraphDocument:
+    """Convert an ontology to a processed OBO Graph JSON document."""
+    return og.StandardizedGraphDocument(graphs=[_to_parsed_graph(obo)])
+
+
+def _to_parsed_graph(obo: Obo) -> og.StandardizedGraph:
+    return og.StandardizedGraph(
+        id=f"http://purl.obolibrary.org/obo/{obo.ontology}.owl",
+        meta=_get_meta(obo),
+        nodes=_get_nodes(obo),
+        edges=_get_edges(obo),
+        equivalent_node_sets=_get_equivalent_node_sets(obo),
+        property_chain_axioms=_get_property_chain_axioms(obo),
+        domain_range_axioms=_get_domain_ranges(obo),
+        logical_definition_axioms=_get_logical_definition_axioms(obo),
+    )
+
+
+def _get_logical_definition_axioms(obo: Obo) -> list[og.StandardizedLogicalDefinition]:
+    rv: list[og.StandardizedLogicalDefinition] = []
+    # TODO
+    return rv
+
+
+def _get_domain_ranges(obo: Obo) -> list[og.StandardizedDomainRangeAxiom]:
+    rv = []
+    for typedef in obo.typedefs or []:
+        if typedef.domain or typedef.range:
+            rv.append(
+                og.StandardizedDomainRangeAxiom(
+                    predicate=typedef.reference,
+                    domains=[typedef.domain] if typedef.domain else [],
+                    ranges=[typedef.range] if typedef.range else [],
+                )
+            )
+    return rv
+
+
+def _get_equivalent_node_sets(obo: Obo) -> list[og.StandardizedEquivalentNodeSet]:
+    rv = []
+    for node in obo:
+        for e in node.equivalent_to:
+            rv.append(og.StandardizedEquivalentNodeSet(node=node.reference, equivalents=[e]))
+    return rv
+
+
+def _get_property_chain_axioms(obo: Obo) -> list[og.StandardizedPropertyChainAxiom]:
+    rv = []
+    for typedef in obo.typedefs or []:
+        for chain in typedef.holds_over_chain:
+            rv.append(
+                og.StandardizedPropertyChainAxiom(
+                    predicate=typedef.reference,
+                    chain=chain,
+                )
+            )
+        # TODO typedef.equivalent_to_chain
+    return rv
+
+
+def _get_meta(obo: Obo) -> og.StandardizedMeta | None:
+    properties = []
+
+    if description := bioregistry.get_description(obo.ontology):
+        properties.append(
+            og.StandardizedProperty(
+                predicate=v.has_description,
+                value=description,
+            )
+        )
+
+        for root_term in obo.root_terms or []:
+            properties.append(
+                og.StandardizedProperty(
+                    predicate=v.has_ontology_root_term,
+                    value=root_term,
+                )
+            )
+
+    if license_spdx_id := bioregistry.get_license(obo.ontology):
+        properties.append(
+            og.StandardizedProperty(
+                predicate=v.has_license,
+                value=license_spdx_id,
+            )
+        )
+
+    if obo.name:
+        properties.append(
+            og.StandardizedProperty(
+                predicate=v.has_title,
+                value=obo.name,
+            )
+        )
+
+    for p in obo.property_values or []:
+        properties.append(
+            og.StandardizedProperty(
+                predicate=p.predicate,
+                value=p.value.value if isinstance(p.value, OBOLiteral) else p.value,
+            )
+        )
+
+    if obo.data_version:
+        version_iri = (
+            f"http://purl.obolibrary.org/obo/{obo.ontology}/{obo.data_version}/{obo.ontology}.owl"
+        )
+    else:
+        version_iri = None
+
+    # comments don't make the round trip
+    subsets = [r for r, _ in obo.subsetdefs or []] or None
+
+    if not properties and not version_iri and not subsets:
+        return None
+
+    return og.StandardizedMeta(
+        properties=properties or None,
+        version_iri=version_iri,
+        subsets=subsets,
+    )
+
+
+def _get_nodes(obo: Obo) -> list[og.StandardizedNode]:
+    rv = []
+    for term in obo:
+        rv.append(_get_class_node(term))
+    for typedef in _get_typedefs(obo):
+        rv.append(_get_typedef_node(typedef))
+    return rv
+
+
+def _get_typedefs(obo: Obo) -> set[TypeDef]:
+    rv = set(obo.typedefs or [])
+    if obo.auto_generated_by:
+        rv.add(tdv.obo_autogenerated_by)
+    return rv
+
+
+def _get_definition(stanza: Stanza) -> og.StandardizedDefinition | None:
+    if not stanza.definition:
+        return None
+    return og.StandardizedDefinition(
+        value=stanza.definition,
+        xrefs=[p for p in stanza.provenance if isinstance(p, curies.Reference)],
+    )
+
+
+def _get_synonyms(stanza: Stanza) -> list[og.StandardizedSynonym] | None:
+    return [
+        og.StandardizedSynonym(
+            text=synonym.name,
+            predicate=v.synonym_scopes[synonym.specificity]
+            if synonym.specificity is not None
+            else v.has_related_synonym,
+            type=synonym.type,
+            xrefs=[p for p in synonym.provenance if isinstance(p, curies.Reference)],
+        )
+        for synonym in stanza.synonyms
+    ] or None
+
+
+def _get_properties(term: Stanza) -> list[og.StandardizedProperty] | None:
+    properties = []
+    for predicate, obj in term.iterate_object_properties():
+        properties.append(
+            og.StandardizedProperty(
+                predicate=predicate,
+                value=obj,
+            )
+        )
+    for predicate, literal in term.iterate_literal_properties():
+        properties.append(
+            og.StandardizedProperty(
+                predicate=predicate,
+                value=literal.value,
+            )
+        )
+    return properties or None
+
+
+def _get_xrefs(stanza: Stanza) -> list[og.StandardizedXref] | None:
+    return [og.StandardizedXref(reference=xref) for xref in stanza.xrefs] or None
+
+
+def _meta_or_none(meta: og.StandardizedMeta) -> og.StandardizedMeta | None:
+    if all(
+        x is None
+        for x in (
+            meta.definition,
+            meta.subsets,
+            meta.xrefs,
+            meta.synonyms,
+            meta.comments,
+            meta.version_iri,
+            meta.properties,
+        )
+    ):
+        return None
+    return meta
+
+
+def _get_class_node(term: Term) -> og.StandardizedNode:
+    meta = og.StandardizedMeta(
+        definition=_get_definition(term),
+        subsets=term.subsets or None,
+        xrefs=_get_xrefs(term),
+        synonyms=_get_synonyms(term),
+        comments=term.get_comments() or None,
+        deprecated=term.is_obsolete or False,
+        properties=_get_properties(term),
+    )
+    return og.StandardizedNode(
+        reference=term.reference,
+        label=term.name,
+        meta=_meta_or_none(meta),
+        type="CLASS" if term.type == "Term" else "INDIVIDUAL",
+    )
+
+
+def _get_typedef_node(typedef: TypeDef) -> og.StandardizedNode:
+    meta = og.StandardizedMeta(
+        definition=_get_definition(typedef),
+        subsets=typedef.subsets or None,
+        xrefs=_get_xrefs(typedef),
+        synonyms=_get_synonyms(typedef),
+        comments=typedef.get_comments() or None,
+        deprecated=typedef.is_obsolete or False,
+        properties=_get_properties(typedef),
+    )
+    return og.StandardizedNode(
+        reference=typedef.reference,
+        label=typedef.name,
+        meta=_meta_or_none(meta),
+        type="PROPERTY",
+        property_type="ANNOTATION" if typedef.is_metadata_tag else "OBJECT",
+    )
+
+
+def _get_edges(obo: Obo) -> list[og.StandardizedEdge]:
+    rv = [
+        og.StandardizedEdge(
+            subject=stanza.reference,
+            predicate=typedef.reference,
+            object=target,
+        )
+        for stanza, typedef, target in obo.iterate_edges(include_xrefs=False)
+    ]
+    return rv

pyobo/struct/obograph/reader.py

@@ -0,0 +1,242 @@
+"""Import of OBO Graph JSON."""
+
+import logging
+from pathlib import Path
+
+import curies
+import obographs
+from curies import Converter
+from curies.vocabulary import SynonymScope, synonym_scopes
+from obographs import (
+    Graph,
+    NodeType,
+    StandardizedGraph,
+    StandardizedMeta,
+    StandardizedNode,
+    StandardizedSynonym,
+)
+
+from pyobo import Obo, Reference, StanzaType, Synonym, Term, TypeDef
+from pyobo.identifier_utils import get_converter
+from pyobo.struct import Annotation, OBOLiteral, make_ad_hoc_ontology
+from pyobo.struct import vocabulary as v
+from pyobo.struct.typedef import has_ontology_root_term
+
+__all__ = [
+    "from_node",
+    "from_obograph",
+    "from_standardized_graph",
+    "read_obograph",
+]
+
+logger = logging.getLogger(__name__)
+
+
+def read_obograph(
+    prefix: str, path: str | Path, *, converter: Converter | None = None, strict: bool = False
+) -> Obo:
+    """Read an OBO Graph JSON file using :func:`obographs.read` then process into a PyOBO structure."""
+    graph = obographs.read(path, squeeze=True)
+    return from_obograph(prefix=prefix, graph=graph, converter=converter, strict=strict)
+
+
+def from_obograph(
+    prefix: str, graph: Graph, *, converter: Converter | None = None, strict: bool = False
+) -> Obo:
+    """Parse a raw OBO Graph JSON into a PyOBO structure."""
+    if converter is None:
+        converter = get_converter()
+    standardized_graph = graph.standardize(converter, strict=strict)
+    return from_standardized_graph(prefix, standardized_graph)
+
+
+def from_standardized_graph(prefix: str, graph: StandardizedGraph) -> Obo:
+    """Generate an OBO data structure from OBO Graph JSON."""
+    terms: dict[Reference, Term] = {}
+    typedefs: dict[Reference, TypeDef] = {}
+    for node in graph.nodes:
+        stanza = from_node(node)
+        match stanza:
+            case Term():
+                terms[stanza.reference] = stanza
+            case TypeDef():
+                typedefs[stanza.reference] = stanza
+
+    for edge in graph.edges:
+        s, p, o = (Reference.from_reference(r) for r in (edge.subject, edge.predicate, edge.object))
+        if s in terms:
+            stanza = terms[s]
+            stanza.append_relationship(p, o)
+        elif s in typedefs:
+            stanza = typedefs[s]
+            stanza.append_relationship(p, o)
+
+    root_terms: list[Reference] = []
+    property_values = []
+    auto_generated_by: str | None = None
+    if graph.meta:
+        for prop in graph.meta.properties or []:
+            predicate = Reference.from_reference(prop.predicate)
+            if predicate == has_ontology_root_term:
+                if isinstance(prop.value, str):
+                    raise TypeError
+                else:
+                    root_terms.append(Reference.from_reference(prop.value))
+            elif predicate == v.obo_autogenerated_by:
+                if not isinstance(prop.value, str):
+                    raise TypeError
+                auto_generated_by = prop.value
+            # TODO specific subsetdef, imports
+            else:
+                property_values.append(
+                    Annotation(
+                        predicate=predicate,
+                        # TODO obographs are limited by ability to specify datatype?
+                        value=OBOLiteral.string(prop.value)
+                        if isinstance(prop.value, str)
+                        else Reference.from_reference(prop.value),
+                    )
+                )
+
+    for equivalent_node_set in graph.equivalent_node_sets:
+        equivalent_reference = Reference.from_reference(equivalent_node_set.node)
+        if equivalent_reference in terms:
+            for equivalent in equivalent_node_set.equivalents:
+                terms[equivalent_reference].append_equivalent_to(
+                    Reference.from_reference(equivalent)
+                )
+        elif equivalent_reference in typedefs:
+            for equivalent in equivalent_node_set.equivalents:
+                typedefs[equivalent_reference].append_equivalent_to(
+                    Reference.from_reference(equivalent)
+                )
+        else:
+            logger.warning(
+                "unknown reference node in equivalent_node_set: %s", equivalent_reference.curie
+            )
+
+    for _domain_range_axiom in graph.domain_range_axioms or []:
+        p = Reference.from_reference(_domain_range_axiom.predicate)
+        if p not in typedefs:
+            continue
+        # the OBO Graph model allows for multiple ranges
+        # or domains, but OBO only one.
+        if _domain_range_axiom.ranges:
+            typedefs[p].range = Reference.from_reference(_domain_range_axiom.ranges[0])
+        if _domain_range_axiom.domains:
+            typedefs[p].domain = Reference.from_reference(_domain_range_axiom.domains[0])
+
+    for _property_chain_axiom in graph.property_chain_axioms:
+        p = Reference.from_reference(_property_chain_axiom.predicate)
+        if p not in typedefs or not _property_chain_axiom.chain:
+            continue
+        # TODO check if its also transitive_over and/or equivalent_to_chain
+        typedefs[p].holds_over_chain.append(
+            [Reference.from_reference(r) for r in _property_chain_axiom.chain]
+        )
+
+    for _logical_definition_axiom in graph.logical_definition_axioms:
+        pass  # TODO
+
+    return make_ad_hoc_ontology(
+        _ontology=prefix,
+        _name=graph.name,
+        terms=list(terms.values()),
+        _typedefs=list(typedefs.values()),
+        _root_terms=root_terms,
+        _property_values=property_values,
+        _data_version=graph.version or (graph.meta.version_iri if graph.meta is not None else None),
+        _auto_generated_by=auto_generated_by,
+    )
+
+
+#: A mapping between OBO Graph JSON node types and OBO stanza types
+MAPPING: dict[NodeType, StanzaType] = {
+    "CLASS": "Term",
+    "INDIVIDUAL": "Instance",
+    "PROPERTY": "TypeDef",
+}
+
+
+def from_node(node: StandardizedNode) -> Term | TypeDef:
+    """Generate a term from a node."""
+    if node.type == "PROPERTY":
+        return _from_property(node)
+    return _from_term(node)
+
+
+def _from_term(node: StandardizedNode) -> Term:
+    term = Term(
+        reference=_get_ref(node),
+        type=MAPPING[node.type] if node.type else "Term",
+    )
+    if node.meta is not None:
+        _process_term_meta(node.meta, term)
+    return term
+
+
+def _from_property(node: StandardizedNode) -> TypeDef:
+    typedef = TypeDef(
+        reference=_get_ref(node),
+        is_metadata_tag=node.property_type == "ANNOTATION",
+    )
+    if node.meta is not None:
+        _process_typedef_meta(node.meta, typedef)
+    return typedef
+
+
+def _get_ref(node: StandardizedNode) -> Reference:
+    return Reference(
+        prefix=node.reference.prefix,
+        identifier=node.reference.identifier,
+        name=node.label,
+    )
+
+
+def _process_term_meta(meta: StandardizedMeta, term: Term) -> None:
+    """Process the ``meta`` object associated with a term node."""
+    if meta.definition:
+        term.definition = meta.definition.value
+        for definition_xref in meta.definition.xrefs or []:
+            term.append_definition_xref(definition_xref)
+
+    if meta.subsets:
+        term.subsets.extend(Reference.from_reference(r) for r in meta.subsets)
+
+    for xref in meta.xrefs or []:
+        term.append_xref(xref.reference)
+
+    for synonym in meta.synonyms or []:
+        if s := _from_synonym(synonym):
+            term.append_synonym(s)
+
+    for comment in meta.comments or []:
+        term.append_comment(comment)
+
+    if meta.deprecated:
+        term.is_obsolete = True
+
+    for prop in meta.properties or []:
+        match prop.value:
+            case Reference():
+                term.annotate_object(prop.predicate, prop.value)
+            case str():
+                # note, OBO Graph format does not allow for annotating data type
+                term.annotate_literal(prop.predicate, OBOLiteral.string(prop.value))
+
+
+REV_SYNONYM_SCOPE: dict[curies.Reference, SynonymScope] = {v: k for k, v in synonym_scopes.items()}
+
+
+def _from_synonym(syn: StandardizedSynonym) -> Synonym | None:
+    return Synonym(
+        name=syn.text,
+        specificity=REV_SYNONYM_SCOPE[syn.predicate],
+        type=Reference.from_reference(syn.type) if syn.type is not None else None,
+        provenance=[Reference.from_reference(r) for r in syn.xrefs or []],
+    )
+
+
+def _process_typedef_meta(meta: StandardizedMeta, typedef: TypeDef) -> None:
+    """Process the ``meta`` object associated with a property node."""
+    # TODO everything else is in here

pyobo/struct/obograph/utils.py

@@ -0,0 +1,47 @@
+"""Testing utilities."""
+
+import unittest
+from typing import cast
+
+from curies import Reference
+from obographs import StandardizedGraph, StandardizedMeta
+
+__all__ = [
+    "assert_graph_equal",
+]
+
+
+def assert_graph_equal(
+    test_case: unittest.TestCase, expected: StandardizedGraph, actual: StandardizedGraph
+) -> None:
+    """Assert two graphs are equal."""
+    if expected.meta is not None:
+        test_case.assertIsNotNone(actual.meta)
+        test_case.assertEqual(
+            expected.meta.model_dump(exclude_unset=True, exclude_none=True, exclude_defaults=True),
+            cast(StandardizedMeta, actual.meta).model_dump(
+                exclude_unset=True, exclude_none=True, exclude_defaults=True
+            ),
+        )
+
+    # strip out extra info
+    for node in actual.nodes:
+        node.reference = Reference.from_reference(node.reference)
+
+    test_case.assertEqual(
+        {node.reference.curie: node for node in expected.nodes},
+        {node.reference.curie: node for node in actual.nodes},
+    )
+    test_case.assertEqual(
+        {node.as_str_triple(): node for node in expected.edges},
+        {node.as_str_triple(): node for node in actual.edges},
+    )
+    excludes = {"nodes", "edges", "meta"}
+    test_case.assertEqual(
+        expected.model_dump(
+            exclude_none=True, exclude_unset=True, exclude_defaults=True, exclude=excludes
+        ),
+        actual.model_dump(
+            exclude_none=True, exclude_unset=True, exclude_defaults=True, exclude=excludes
+        ),
+    )