pyobo 0.11.2__py3-none-any.whl → 0.12.0__py3-none-any.whl

pyobo/api/hierarchy.py

@@ -1,291 +1,319 @@
 """High-level API for hierarchies."""
 
 import logging
+import warnings
 from collections.abc import Iterable
 from functools import lru_cache
-from typing import Optional
+from typing import overload
 
 import networkx as nx
-
-from .names import get_name
-from .properties import get_filtered_properties_mapping
-from .relations import get_filtered_relations_df
-from ..identifier_utils import wrap_norm_prefix
-from ..struct import TypeDef, has_member, is_a, part_of
+from curies import ReferenceTuple
+from typing_extensions import NotRequired, Unpack
+
+from .edges import get_edges
+from .names import get_name, get_references
+from .properties import get_literal_properties
+from .utils import _get_pi
+from ..constants import GetOntologyKwargs
+from ..struct import has_member, has_part, is_a, member_of, part_of
 from ..struct.reference import Reference
+from ..struct.struct_utils import ReferenceHint, _ensure_ref
 
 __all__ = [
+    "get_ancestors",
+    "get_children",
+    "get_descendants",
     "get_hierarchy",
     "get_subhierarchy",
-    "get_descendants",
-    "get_ancestors",
     "has_ancestor",
     "is_descendent",
-    "get_children",
 ]
 
-
 logger = logging.getLogger(__name__)
 
 
+class HierarchyKwargs(GetOntologyKwargs):
+    """Keyword argument hints for hierarchy getter functions."""
+
+    include_part_of: NotRequired[bool]
+    include_has_member: NotRequired[bool]
+
+
 def get_hierarchy(
     prefix: str,
     *,
-    include_part_of: bool = True,
-    include_has_member: bool = False,
-    extra_relations: Optional[Iterable[TypeDef]] = None,
-    properties: Optional[Iterable[str]] = None,
-    use_tqdm: bool = False,
-    force: bool = False,
-    version: Optional[str] = None,
+    extra_relations: Iterable[ReferenceHint] | None = None,
+    properties: Iterable[ReferenceHint] | None = None,
+    **kwargs: Unpack[HierarchyKwargs],
 ) -> nx.DiGraph:
     """Get hierarchy of parents as a directed graph.
 
     :param prefix: The name of the namespace.
-    :param include_part_of: Add "part of" relations. Only works if the relations are properly
-        defined using bfo:0000050 ! part of or bfo:0000051 ! has part
-    :param include_has_member: Add "has member" relations. These aren't part of the BFO, but
-        are hacked into PyOBO using :data:`pyobo.struct.typedef.has_member` for relationships like
-        from protein families to their actual proteins.
-    :param extra_relations: Other relations that you want to include in the hierarchy. For
-        example, it might be useful to include the positively_regulates
-    :param properties: Properties to include in the data part of each node. For example, might want
-        to include SMILES strings with the ChEBI tree.
-    :param use_tqdm: Show a progress bar
+    :param include_part_of: Add "part of" relations. Only works if the relations are
+        properly defined using bfo:0000050 ! part of or bfo:0000051 ! has part
+    :param include_has_member: Add "has member" relations. These aren't part of the BFO,
+        but are hacked into PyOBO using :data:`pyobo.struct.typedef.has_member` for
+        relationships like from protein families to their actual proteins.
+    :param extra_relations: Other relations that you want to include in the hierarchy.
+        For example, it might be useful to include the positively_regulates
+    :param properties: Properties to include in the data part of each node. For example,
+        might want to include SMILES strings with the ChEBI tree.
     :param force: should the resources be reloaded when extracting relations?
+
     :returns: A directional graph representing the hierarchy
 
-    This function thinly wraps :func:`_get_hierarchy_helper` to make it easier to work with the lru_cache mechanism.
+    This function thinly wraps :func:`_get_hierarchy_helper` to make it easier to work
+    with the lru_cache mechanism.
     """
     return _get_hierarchy_helper(
         prefix=prefix,
-        include_part_of=include_part_of,
-        include_has_member=include_has_member,
-        extra_relations=tuple(sorted(extra_relations or [], key=lambda t: t.curie)),
-        properties=tuple(sorted(properties or [])),
-        use_tqdm=use_tqdm,
-        force=force,
-        version=version,
+        extra_relations=_tp(prefix, extra_relations),
+        properties=_tp(prefix, properties),
+        **kwargs,
+    )
+
+
+def _tp(prefix: str, references: Iterable[ReferenceHint] | None) -> tuple[Reference, ...]:
+    return tuple(
+        sorted(_ensure_ref(reference, ontology_prefix=prefix) for reference in references or [])
     )
 
 
 @lru_cache
-@wrap_norm_prefix
 def _get_hierarchy_helper(
     prefix: str,
     *,
-    extra_relations: tuple[TypeDef, ...],
-    properties: tuple[str, ...],
-    include_part_of: bool,
-    include_has_member: bool,
-    use_tqdm: bool,
-    force: bool = False,
-    version: Optional[str] = None,
+    extra_relations: tuple[Reference, ...],
+    properties: tuple[Reference, ...],
+    include_part_of: bool = False,
+    include_has_member: bool = False,
+    **kwargs: Unpack[GetOntologyKwargs],
 ) -> nx.DiGraph:
+    predicates, reverse_predicates = _get_predicate_sets(
+        extra_relations, include_part_of, include_has_member
+    )
+
     rv = nx.DiGraph()
+    rv.add_nodes_from(get_references(prefix, **kwargs))
 
-    is_a_df = get_filtered_relations_df(
-        prefix=prefix,
-        relation=is_a,
-        use_tqdm=use_tqdm,
-        force=force,
-        version=version,
-    )
-    for source_id, target_ns, target_id in is_a_df.values:
-        rv.add_edge(f"{prefix}:{source_id}", f"{target_ns}:{target_id}", relation="is_a")
+    for s, p, o in get_edges(prefix, **kwargs):
+        if p in predicates:
+            rv.add_edge(s, o, relation=p)
+        elif p in reverse_predicates:
+            rv.add_edge(o, s, relation=p)
 
-    if include_has_member:
-        has_member_df = get_filtered_relations_df(
-            prefix=prefix,
-            relation=has_member,
-            use_tqdm=use_tqdm,
-            force=force,
-            version=version,
-        )
-        for target_id, source_ns, source_id in has_member_df.values:
-            rv.add_edge(f"{source_ns}:{source_id}", f"{prefix}:{target_id}", relation="is_a")
+    properties_ = set(properties)
+    for s, p, op in get_literal_properties(prefix, **kwargs):
+        if s in rv and p in properties_:
+            rv.nodes[s][p] = op.value
+
+    return rv
 
+
+def _get_predicate_sets(
+    extra_relations: Iterable[Reference], include_part_of: bool, include_has_member: bool
+) -> tuple[set[Reference], set[Reference]]:
+    predicates: set[Reference] = {is_a.reference, *extra_relations}
+    reverse_predicates: set[Reference] = set()
     if include_part_of:
-        part_of_df = get_filtered_relations_df(
-            prefix=prefix,
-            relation=part_of,
-            use_tqdm=use_tqdm,
-            force=force,
-            version=version,
-        )
-        for source_id, target_ns, target_id in part_of_df.values:
-            rv.add_edge(f"{prefix}:{source_id}", f"{target_ns}:{target_id}", relation="part_of")
-
-        has_part_df = get_filtered_relations_df(
-            prefix=prefix,
-            relation=part_of,
-            use_tqdm=use_tqdm,
-            force=force,
-            version=version,
-        )
-        for target_id, source_ns, source_id in has_part_df.values:
-            rv.add_edge(f"{source_ns}:{source_id}", f"{prefix}:{target_id}", relation="part_of")
-
-    for relation in extra_relations:
-        if not isinstance(relation, (TypeDef, Reference)):
-            raise TypeError
-        relation_df = get_filtered_relations_df(
-            prefix=prefix,
-            relation=relation,
-            use_tqdm=use_tqdm,
-            force=force,
-            version=version,
-        )
-        for source_id, target_ns, target_id in relation_df.values:
-            rv.add_edge(
-                f"{prefix}:{source_id}", f"{target_ns}:{target_id}", relation=relation.identifier
-            )
-
-    for prop in properties:
-        props = get_filtered_properties_mapping(
-            prefix=prefix, prop=prop, use_tqdm=use_tqdm, force=force
-        )
-        for identifier, value in props.items():
-            curie = f"{prefix}:{identifier}"
-            if curie in rv:
-                rv.nodes[curie][prop] = value
+        predicates.add(part_of.reference)
+        reverse_predicates.add(has_part.reference)
+    if include_has_member:
+        predicates.add(has_member.reference)
+        reverse_predicates.add(member_of.reference)
+    return predicates, reverse_predicates
 
-    return rv
 
+# docstr-coverage:excused `overload`
+@overload
+def is_descendent(
+    prefix: str,
+    identifier: str,
+    ancestor_prefix: str = ...,
+    ancestor_identifier: str = ...,
+    /,
+    **kwargs: Unpack[HierarchyKwargs],
+) -> bool: ...
 
+
+# docstr-coverage:excused `overload`
+@overload
 def is_descendent(
-    prefix, identifier, ancestor_prefix, ancestor_identifier, *, version: Optional[str] = None
+    descendant: Reference,
+    ancestor: Reference,
+    _1: None = ...,
+    _2: None = ...,
+    /,
+    **kwargs: Unpack[HierarchyKwargs],
+) -> bool: ...
+
+
+def is_descendent(
+    prefix: str | Reference,
+    identifier: str | Reference,
+    ancestor_prefix: str | None = None,
+    ancestor_identifier: str | None = None,
+    /,
+    **kwargs: Unpack[HierarchyKwargs],
 ) -> bool:
     """Check that the first identifier has the second as a descendent.
 
-    Check that go:0070246 ! natural killer cell apoptotic process is a
-    descendant of go:0006915 ! apoptotic process::
+    :param prefix: The prefix for the descendant
+    :param identifier: The local unique identifier for the descendant
+    :param ancestor_prefix: The prefix for the ancestor
+    :param ancestor_identifier: The local unique identifier for the ancestor
+    :param kwargs: Keyword arguments for :func:`get_hierarchy`
+    :return: If the decendant has the given ancestor
+
+    Check that ``GO:0070246`` (natural killer cell apoptotic process) is a descendant of
+    ``GO:0006915`` (apoptotic process)
+
+    >>> nk_apoptosis = Reference.from_curie(
+    ...     "GO:0070246", name="natural killer cell apoptotic process"
+    ... )
+    >>> apoptosis = Reference.from_curie("GO:0006915", name="apoptotic process")
+    >>> assert is_descendent(nk_apoptosis, apoptosis)
+
+    Using deprecated old-style arguments:
+
     >>> assert is_descendent("go", "0070246", "go", "0006915")
     """
-    descendants = get_descendants(ancestor_prefix, ancestor_identifier, version=version)
-    return descendants is not None and f"{prefix}:{identifier}" in descendants
+    descendant, ancestor = _get_double_reference(
+        prefix, identifier, ancestor_prefix, ancestor_identifier
+    )
+    descendants = get_descendants(ancestor, **kwargs)
+    return descendants is not None and descendant in descendants
 
 
 @lru_cache
 def get_descendants(
-    prefix: str,
-    identifier: Optional[str] = None,
-    include_part_of: bool = True,
-    include_has_member: bool = False,
-    use_tqdm: bool = False,
-    force: bool = False,
-    **kwargs,
-) -> Optional[set[str]]:
+    prefix: str | Reference | ReferenceTuple,
+    identifier: str | None = None,
+    /,
+    **kwargs: Unpack[HierarchyKwargs],
+) -> set[Reference] | None:
     """Get all the descendants (children) of the term as CURIEs."""
-    curie, prefix, identifier = _pic(prefix, identifier)
-    hierarchy = get_hierarchy(
-        prefix=prefix,
-        include_has_member=include_has_member,
-        include_part_of=include_part_of,
-        use_tqdm=use_tqdm,
-        force=force,
-        **kwargs,
-    )
-    if curie not in hierarchy:
+    t = _get_pi(prefix, identifier)
+    hierarchy = get_hierarchy(prefix=t.prefix, **kwargs)
+    if t not in hierarchy:
         return None
-    return nx.ancestors(hierarchy, curie)  # note this is backwards
-
-
-def _pic(prefix, identifier=None) -> tuple[str, str, str]:
-    if identifier is None:
-        curie = prefix
-        prefix, identifier = prefix.split(":")
-    else:
-        curie = f"{prefix}:{identifier}"
-    return curie, prefix, identifier
+    return nx.ancestors(hierarchy, t)  # note this is backwards
 
 
 @lru_cache
 def get_children(
-    prefix: str,
-    identifier: Optional[str] = None,
-    include_part_of: bool = True,
-    include_has_member: bool = False,
-    use_tqdm: bool = False,
-    force: bool = False,
-    **kwargs,
-) -> Optional[set[str]]:
+    prefix: str | Reference | ReferenceTuple,
+    identifier: str | None = None,
+    /,
+    **kwargs: Unpack[HierarchyKwargs],
+) -> set[Reference] | None:
     """Get all the descendants (children) of the term as CURIEs."""
-    curie, prefix, identifier = _pic(prefix, identifier)
-    hierarchy = get_hierarchy(
-        prefix=prefix,
-        include_has_member=include_has_member,
-        include_part_of=include_part_of,
-        use_tqdm=use_tqdm,
-        force=force,
-        **kwargs,
-    )
-    if curie not in hierarchy:
+    t = _get_pi(prefix, identifier)
+    hierarchy = get_hierarchy(prefix=t.prefix, **kwargs)
+    if t not in hierarchy:
         return None
-    return set(hierarchy.predecessors(curie))
+    return set(hierarchy.predecessors(t))
+
+
+# docstr-coverage:excused `overload`
+@overload
+def has_ancestor(
+    prefix: str,
+    identifier: str,
+    ancestor_prefix: str = ...,
+    ancestor_identifier: str = ...,
+    /,
+    **kwargs: Unpack[HierarchyKwargs],
+) -> bool: ...
+
+
+# docstr-coverage:excused `overload`
+@overload
+def has_ancestor(
+    descendant: Reference,
+    ancestor: Reference,
+    _1: None = ...,
+    _2: None = ...,
+    /,
+    **kwargs: Unpack[HierarchyKwargs],
+) -> bool: ...
 
 
 def has_ancestor(
-    prefix, identifier, ancestor_prefix, ancestor_identifier, *, version: Optional[str] = None
+    prefix: str | Reference,
+    identifier: str | Reference,
+    ancestor_prefix: str | None = None,
+    ancestor_identifier: str | None = None,
+    /,
+    **kwargs: Unpack[HierarchyKwargs],
 ) -> bool:
     """Check that the first identifier has the second as an ancestor.
 
-    Check that go:0008219 ! cell death is an ancestor of go:0006915 ! apoptotic process::
+    :param prefix: The prefix for the descendant
+    :param identifier: The local unique identifier for the descendant
+    :param ancestor_prefix: The prefix for the ancestor
+    :param ancestor_identifier: The local unique identifier for the ancestor
+    :param kwargs: Keyword arguments for :func:`get_hierarchy`
+    :return: If the decendant has the given ancestor
+
+    Check that ``GO:0008219`` (cell death) is an ancestor of ``GO:0006915``
+    (apoptotic process):
+
+    >>> apoptosis = Reference.from_curie("GO:0006915", name="apoptotic process")
+    >>> cell_death = Reference.from_curie("GO:0008219", name="cell death")
+    >>> assert has_ancestor(apoptosis, cell_death)
+
+    The same, using the deprecated argumentation style:
+
     >>> assert has_ancestor("go", "0006915", "go", "0008219")
     """
-    ancestors = get_ancestors(prefix, identifier, version=version)
-    return ancestors is not None and f"{ancestor_prefix}:{ancestor_identifier}" in ancestors
+    descendant, ancestor = _get_double_reference(
+        prefix, identifier, ancestor_prefix, ancestor_identifier
+    )
+    ancestors = get_ancestors(descendant, **kwargs)
+    return ancestors is not None and ancestor in ancestors
+
+
+def _get_double_reference(
+    a: str | Reference, b: str | Reference, c: str | None, d: str | None
+) -> tuple[Reference, Reference]:
+    if isinstance(a, Reference) and isinstance(b, Reference):
+        return a, b
+    elif all(isinstance(x, str) for x in (a, b, c, d)):
+        warnings.warn("passing strings is deprecated", DeprecationWarning, stacklevel=2)
+        return Reference(prefix=a, identifier=b), Reference(prefix=c, identifier=d)
+    else:
+        raise TypeError
 
 
 @lru_cache
 def get_ancestors(
-    prefix: str,
-    identifier: Optional[str] = None,
-    include_part_of: bool = True,
-    include_has_member: bool = False,
-    use_tqdm: bool = False,
-    force: bool = False,
-    **kwargs,
-) -> Optional[set[str]]:
+    prefix: str | Reference | ReferenceTuple,
+    identifier: str | None = None,
+    /,
+    **kwargs: Unpack[HierarchyKwargs],
+) -> set[Reference] | None:
     """Get all the ancestors (parents) of the term as CURIEs."""
-    curie, prefix, identifier = _pic(prefix, identifier)
-    hierarchy = get_hierarchy(
-        prefix=prefix,
-        include_has_member=include_has_member,
-        include_part_of=include_part_of,
-        use_tqdm=use_tqdm,
-        force=force,
-        **kwargs,
-    )
-    if curie not in hierarchy:
+    t = _get_pi(prefix, identifier)
+    hierarchy = get_hierarchy(prefix=t.prefix, **kwargs)
+    if t not in hierarchy:
         return None
-    return nx.descendants(hierarchy, curie)  # note this is backwards
+
+    return nx.descendants(hierarchy, t)  # note this is backwards
 
 
 def get_subhierarchy(
-    prefix: str,
-    identifier: Optional[str] = None,
-    include_part_of: bool = True,
-    include_has_member: bool = False,
-    use_tqdm: bool = False,
-    force: bool = False,
-    **kwargs,
+    prefix: str | Reference | ReferenceTuple,
+    identifier: str | None = None,
+    /,
+    **kwargs: Unpack[HierarchyKwargs],
 ) -> nx.DiGraph:
     """Get the subhierarchy for a given node."""
-    curie, prefix, identifier = _pic(prefix, identifier)
-    hierarchy = get_hierarchy(
-        prefix=prefix,
-        include_has_member=include_has_member,
-        include_part_of=include_part_of,
-        use_tqdm=use_tqdm,
-        force=force,
-        **kwargs,
-    )
-    logger.info(
-        "getting descendants of %s:%s ! %s", prefix, identifier, get_name(prefix, identifier)
-    )
-    curies = nx.ancestors(hierarchy, curie)  # note this is backwards
+    t = _get_pi(prefix, identifier)
+    hierarchy = get_hierarchy(prefix=t.prefix, **kwargs)
+    logger.info("getting descendants of %s ! %s", t.curie, get_name(t))
+    descendants = set(nx.ancestors(hierarchy, t)) | {t}  # note this is backwards
     logger.info("inducing subgraph")
-    sg = hierarchy.subgraph(curies).copy()
+    sg = hierarchy.subgraph(descendants).copy()
     logger.info("subgraph has %d nodes/%d edges", sg.number_of_nodes(), sg.number_of_edges())
     return sg

pyobo/api/metadata.py

@@ -1,15 +1,17 @@
 """High-level API for metadata."""
 
 import logging
-from collections.abc import Mapping
 from functools import lru_cache
-from typing import Optional
+from typing import Any, cast
 
-from .utils import get_version
+from typing_extensions import Unpack
+
+from .utils import get_version_from_kwargs
+from ..constants import GetOntologyKwargs, check_should_force
 from ..getters import get_ontology
 from ..identifier_utils import wrap_norm_prefix
 from ..utils.cache import cached_json
-from ..utils.path import prefix_cache_join
+from ..utils.path import CacheArtifact, get_cache_path
 
 __all__ = [
     "get_metadata",
@@ -20,21 +22,14 @@ logger = logging.getLogger(__name__)
 
 @lru_cache
 @wrap_norm_prefix
-def get_metadata(
-    prefix: str, *, force: bool = False, version: Optional[str] = None
-) -> Mapping[str, str]:
+def get_metadata(prefix: str, **kwargs: Unpack[GetOntologyKwargs]) -> dict[str, Any]:
     """Get metadata for the ontology."""
-    if version is None:
-        version = get_version(prefix)
-    path = prefix_cache_join(prefix, name="metadata.json", version=version)
-
-    @cached_json(path=path, force=force)
-    def _get_json() -> Mapping[str, str]:
-        if force:
-            logger.debug("[%s] forcing reload for metadata", prefix)
-        else:
-            logger.debug("[%s] no cached metadata found. getting from OBO loader", prefix)
-        ontology = get_ontology(prefix, force=force, version=version)
+    version = get_version_from_kwargs(prefix, kwargs)
+    path = get_cache_path(prefix, CacheArtifact.metadata, version=version)
+
+    @cached_json(path=path, force=check_should_force(kwargs))
+    def _get_json() -> dict[str, Any]:
+        ontology = get_ontology(prefix, **kwargs)
         return ontology.get_metadata()
 
-    return _get_json()
+    return cast(dict[str, Any], _get_json())