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

pyobo/__init__.py

@@ -1,11 +1,13 @@
 """A python package for handling and generating OBO."""
 
-from .api import (  # noqa: F401
+from .api import (
     get_alts_to_id,
     get_ancestors,
     get_children,
     get_definition,
     get_descendants,
+    get_edges,
+    get_edges_df,
     get_filtered_properties_df,
     get_filtered_properties_mapping,
     get_filtered_properties_multimapping,
@@ -20,15 +22,25 @@ from .api import (  # noqa: F401
     get_id_synonyms_mapping,
     get_id_to_alts,
     get_ids,
+    get_literal_mappings,
+    get_literal_mappings_df,
+    get_literal_mappings_subset,
+    get_literal_properties,
+    get_literal_properties_df,
+    get_mappings_df,
+    get_metadata,
     get_name,
     get_name_by_curie,
     get_name_id_mapping,
+    get_object_properties,
+    get_object_properties_df,
     get_obsolete,
     get_primary_curie,
     get_primary_identifier,
     get_properties,
     get_properties_df,
     get_property,
+    get_references,
     get_relation,
     get_relation_mapping,
     get_relations_df,
@@ -43,26 +55,89 @@ from .api import (  # noqa: F401
     has_ancestor,
     is_descendent,
 )
-from .getters import get_ontology  # noqa: F401
-from .identifier_utils import normalize_curie  # noqa: F401
-from .normalizer import OboNormalizer, ground  # noqa: F401
-from .obographs import parse_results_from_obo  # noqa: F401
-from .plugins import (  # noqa: F401
+from .getters import get_ontology
+from .ner import get_grounder, ground
+from .obographs import parse_results_from_obo
+from .plugins import (
     has_nomenclature_plugin,
     iter_nomenclature_plugins,
     run_nomenclature_plugin,
 )
-from .reader import from_obo_path, from_obonet  # noqa: F401
-from .struct import Obo, Reference, Synonym, SynonymTypeDef, Term, TypeDef  # noqa: F401
-from .utils.path import ensure_path  # noqa: F401
-from .version import get_version  # noqa: F401
-from .xrefdb.canonicalizer import (  # noqa: F401
-    Canonicalizer,
-    get_equivalent,
-    get_priority_curie,
-)
-from .xrefdb.sources import (  # noqa: F401
-    has_xref_plugin,
-    iter_xref_plugins,
-    run_xref_plugin,
-)
+from .reader import from_obo_path, from_obonet
+from .struct import Obo, Reference, Synonym, SynonymTypeDef, Term, TypeDef, default_reference
+from .utils.path import ensure_path
+from .version import get_version
+
+__all__ = [
+    "Obo",
+    "Reference",
+    "Synonym",
+    "SynonymTypeDef",
+    "Term",
+    "TypeDef",
+    "default_reference",
+    "ensure_path",
+    "from_obo_path",
+    "from_obonet",
+    "get_alts_to_id",
+    "get_ancestors",
+    "get_children",
+    "get_definition",
+    "get_descendants",
+    "get_edges",
+    "get_edges_df",
+    "get_filtered_properties_df",
+    "get_filtered_properties_mapping",
+    "get_filtered_properties_multimapping",
+    "get_filtered_relations_df",
+    "get_filtered_xrefs",
+    "get_graph",
+    "get_grounder",
+    "get_hierarchy",
+    "get_id_definition_mapping",
+    "get_id_multirelations_mapping",
+    "get_id_name_mapping",
+    "get_id_species_mapping",
+    "get_id_synonyms_mapping",
+    "get_id_to_alts",
+    "get_ids",
+    "get_literal_mappings",
+    "get_literal_mappings_df",
+    "get_literal_mappings_subset",
+    "get_literal_properties",
+    "get_literal_properties_df",
+    "get_mappings_df",
+    "get_metadata",
+    "get_name",
+    "get_name_by_curie",
+    "get_name_id_mapping",
+    "get_object_properties",
+    "get_object_properties_df",
+    "get_obsolete",
+    "get_ontology",
+    "get_primary_curie",
+    "get_primary_identifier",
+    "get_properties",
+    "get_properties_df",
+    "get_property",
+    "get_references",
+    "get_relation",
+    "get_relation_mapping",
+    "get_relations_df",
+    "get_species",
+    "get_sssom_df",
+    "get_subhierarchy",
+    "get_synonyms",
+    "get_typedef_df",
+    "get_version",
+    "get_xref",
+    "get_xrefs",
+    "get_xrefs_df",
+    "ground",
+    "has_ancestor",
+    "has_nomenclature_plugin",
+    "is_descendent",
+    "iter_nomenclature_plugins",
+    "parse_results_from_obo",
+    "run_nomenclature_plugin",
+]

pyobo/api/__init__.py

@@ -1,12 +1,14 @@
 """High-level API for accessing content."""
 
-from .alts import (  # noqa: F401
+from .alts import (
     get_alts_to_id,
     get_id_to_alts,
     get_primary_curie,
     get_primary_identifier,
 )
-from .hierarchy import (  # noqa: F401
+from .combine import get_literal_mappings_subset
+from .edges import get_edges, get_edges_df, get_graph
+from .hierarchy import (
     get_ancestors,
     get_children,
     get_descendants,
@@ -15,41 +17,110 @@ from .hierarchy import (  # noqa: F401
     has_ancestor,
     is_descendent,
 )
-from .metadata import get_metadata  # noqa: F401
-from .names import (  # noqa: F401
+from .metadata import get_metadata
+from .names import (
     get_definition,
     get_id_definition_mapping,
     get_id_name_mapping,
     get_id_synonyms_mapping,
     get_ids,
+    get_literal_mappings,
+    get_literal_mappings_df,
     get_name,
     get_name_by_curie,
     get_name_id_mapping,
     get_obsolete,
+    get_obsolete_references,
+    get_references,
     get_synonyms,
 )
-from .properties import (  # noqa: F401
+from .properties import (
     get_filtered_properties_df,
     get_filtered_properties_mapping,
     get_filtered_properties_multimapping,
+    get_literal_properties,
+    get_literal_properties_df,
+    get_object_properties,
+    get_object_properties_df,
     get_properties,
     get_properties_df,
     get_property,
 )
-from .relations import (  # noqa: F401
+from .relations import (
     get_filtered_relations_df,
-    get_graph,
     get_id_multirelations_mapping,
     get_relation,
     get_relation_mapping,
     get_relations_df,
 )
-from .species import get_id_species_mapping, get_species  # noqa: F401
-from .typedefs import get_typedef_df  # noqa: F401
-from .xrefs import (  # noqa: F401
+from .species import get_id_species_mapping, get_species
+from .typedefs import get_typedef_df
+from .xrefs import (
     get_filtered_xrefs,
+    get_mappings_df,
     get_sssom_df,
     get_xref,
     get_xrefs,
     get_xrefs_df,
 )
+
+__all__ = [
+    "get_alts_to_id",
+    "get_ancestors",
+    "get_children",
+    "get_definition",
+    "get_descendants",
+    "get_edges",
+    "get_edges_df",
+    "get_equivalent",
+    "get_filtered_properties_df",
+    "get_filtered_properties_mapping",
+    "get_filtered_properties_multimapping",
+    "get_filtered_relations_df",
+    "get_filtered_xrefs",
+    "get_graph",
+    "get_hierarchy",
+    "get_id_definition_mapping",
+    "get_id_multirelations_mapping",
+    "get_id_name_mapping",
+    "get_id_species_mapping",
+    "get_id_synonyms_mapping",
+    "get_id_to_alts",
+    "get_ids",
+    "get_literal_mappings",
+    "get_literal_mappings_df",
+    "get_literal_mappings_subset",
+    "get_literal_properties",
+    "get_literal_properties_df",
+    "get_mappings_df",
+    "get_metadata",
+    "get_name",
+    "get_name_by_curie",
+    "get_name_id_mapping",
+    "get_object_properties",
+    "get_object_properties_df",
+    "get_obsolete",
+    "get_obsolete_references",
+    "get_ontology",
+    "get_primary_curie",
+    "get_primary_identifier",
+    "get_priority_curie",
+    "get_properties",
+    "get_properties_df",
+    "get_property",
+    "get_references",
+    "get_relation",
+    "get_relation_mapping",
+    "get_relations_df",
+    "get_species",
+    "get_sssom_df",
+    "get_subhierarchy",
+    "get_synonyms",
+    "get_typedef_df",
+    "get_version",
+    "get_xref",
+    "get_xrefs",
+    "get_xrefs_df",
+    "has_ancestor",
+    "is_descendent",
+]

pyobo/api/alts.py

@@ -3,17 +3,21 @@
 import logging
 from collections.abc import Mapping
 from functools import lru_cache
-from typing import Optional
 
-from .utils import get_version
+import curies
+from pydantic import ValidationError
+from typing_extensions import Unpack
+
+from .utils import _get_pi, get_version_from_kwargs
+from ..constants import GetOntologyKwargs, check_should_cache, check_should_force
 from ..getters import get_ontology
-from ..identifier_utils import normalize_curie, wrap_norm_prefix
+from ..identifier_utils import wrap_norm_prefix
 from ..utils.cache import cached_multidict
-from ..utils.path import prefix_cache_join
+from ..utils.path import CacheArtifact, get_cache_path
 
 __all__ = [
-    "get_id_to_alts",
     "get_alts_to_id",
+    "get_id_to_alts",
     "get_primary_curie",
     "get_primary_identifier",
 ]
@@ -27,25 +31,22 @@ NO_ALTS = {
 
 @lru_cache
 @wrap_norm_prefix
-def get_id_to_alts(
-    prefix: str, *, force: bool = False, version: Optional[str] = None
-) -> Mapping[str, list[str]]:
+def get_id_to_alts(prefix: str, **kwargs: Unpack[GetOntologyKwargs]) -> Mapping[str, list[str]]:
     """Get alternate identifiers."""
     if prefix in NO_ALTS:
         return {}
 
-    if version is None:
-        version = get_version(prefix)
-    path = prefix_cache_join(prefix, name="alt_ids.tsv", version=version)
-    header = [f"{prefix}_id", "alt_id"]
+    version = get_version_from_kwargs(prefix, kwargs)
+    path = get_cache_path(prefix, CacheArtifact.alts, version=version)
 
-    @cached_multidict(path=path, header=header, force=force)
+    @cached_multidict(
+        path=path,
+        header=[f"{prefix}_id", "alt_id"],
+        cache=check_should_cache(kwargs),
+        force=check_should_force(kwargs),
+    )
     def _get_mapping() -> Mapping[str, list[str]]:
-        if force:
-            logger.info(f"[{prefix}] forcing reload for alts")
-        else:
-            logger.info("[%s] no cached alts found. getting from OBO loader", prefix)
-        ontology = get_ontology(prefix, force=force, version=version)
+        ontology = get_ontology(prefix, **kwargs)
         return ontology.get_id_alts_mapping()
 
     return _get_mapping()
@@ -53,40 +54,49 @@ def get_id_to_alts(
 
 @lru_cache
 @wrap_norm_prefix
-def get_alts_to_id(
-    prefix: str, *, force: bool = False, version: Optional[str] = None
-) -> Mapping[str, str]:
+def get_alts_to_id(prefix: str, **kwargs: Unpack[GetOntologyKwargs]) -> Mapping[str, str]:
     """Get alternative id to primary id mapping."""
     return {
-        alt: primary
-        for primary, alts in get_id_to_alts(prefix, force=force, version=version).items()
-        for alt in alts
+        alt: primary for primary, alts in get_id_to_alts(prefix, **kwargs).items() for alt in alts
     }
 
 
-def get_primary_curie(curie: str, *, version: Optional[str] = None) -> Optional[str]:
+def get_primary_curie(
+    prefix: str | curies.Reference | curies.ReferenceTuple,
+    identifier: str | None = None,
+    /,
+    **kwargs: Unpack[GetOntologyKwargs],
+) -> str | None:
     """Get the primary curie for an entity."""
-    prefix, identifier = normalize_curie(curie)
-    primary_identifier = get_primary_identifier(prefix, identifier, version=version)
-    if primary_identifier is not None:
-        return f"{prefix}:{primary_identifier}"
-    return None
-
-
-@wrap_norm_prefix
-def get_primary_identifier(prefix: str, identifier: str, *, version: Optional[str] = None) -> str:
+    reference = _get_pi(prefix, identifier)
+    try:
+        primary_identifier = get_primary_identifier(reference, **kwargs)
+    except (ValueError, ValidationError):
+        if kwargs.get("strict"):
+            raise
+        # this happens on invalid prefix. maybe revise?
+        return None
+    return f"{reference.prefix}:{primary_identifier}"
+
+
+def get_primary_identifier(
+    prefix: str | curies.Reference | curies.ReferenceTuple,
+    identifier: str | None = None,
+    /,
+    **kwargs: Unpack[GetOntologyKwargs],
+) -> str:
     """Get the primary identifier for an entity.
 
     :param prefix: The name of the resource
     :param identifier: The identifier to look up
+
     :returns: the canonical identifier based on alt id lookup
 
-    Returns the original identifier if there are no alts available or if there's no mapping.
+    Returns the original identifier if there are no alts available or if there's no
+    mapping.
     """
-    if prefix in NO_ALTS:  # TODO later expand list to other namespaces with no alts
-        return identifier
-
-    alts_to_id = get_alts_to_id(prefix, version=version)
-    if alts_to_id and identifier in alts_to_id:
-        return alts_to_id[identifier]
-    return identifier
+    t = _get_pi(prefix, identifier)
+    if t.prefix in NO_ALTS:  # TODO later expand list to other namespaces with no alts
+        return t.identifier
+    alts_to_id = get_alts_to_id(t.prefix, **kwargs)
+    return alts_to_id.get(t.identifier, t.identifier)

pyobo/api/combine.py

@@ -0,0 +1,39 @@
+"""Functions that combine other API aspects."""
+
+from collections.abc import Sequence
+
+import curies
+import ssslm
+from typing_extensions import Unpack
+
+from pyobo.api.hierarchy import get_descendants
+from pyobo.api.names import get_literal_mappings
+from pyobo.constants import GetOntologyKwargs
+from pyobo.struct import Reference
+
+__all__ = [
+    "get_literal_mappings_subset",
+]
+
+
+def get_literal_mappings_subset(
+    prefix: str,
+    ancestors: curies.Reference | Sequence[curies.Reference],
+    *,
+    skip_obsolete: bool = False,
+    **kwargs: Unpack[GetOntologyKwargs],
+) -> list[ssslm.LiteralMapping]:
+    """Get a subset of literal mappings under the given ancestors."""
+    if isinstance(ancestors, curies.Reference):
+        ancestors = [ancestors]
+
+    subset: set[Reference] = {
+        descendant
+        for ancestor in ancestors
+        for descendant in get_descendants(ancestor, **kwargs) or []
+    }
+    return [
+        literal_mapping
+        for literal_mapping in get_literal_mappings(prefix, skip_obsolete=skip_obsolete, **kwargs)
+        if literal_mapping.reference in subset
+    ]

pyobo/api/edges.py

@@ -0,0 +1,68 @@
+"""High-level API for edges."""
+
+import networkx as nx
+import pandas as pd
+from tqdm import tqdm
+from typing_extensions import Unpack
+
+from pyobo.api.names import get_ids
+from pyobo.api.utils import get_version_from_kwargs
+from pyobo.constants import (
+    GetOntologyKwargs,
+    check_should_cache,
+    check_should_force,
+    check_should_use_tqdm,
+)
+from pyobo.getters import get_ontology
+
+from ..struct import Reference
+from ..utils.cache import cached_df
+from ..utils.path import CacheArtifact, get_cache_path
+
+__all__ = [
+    "get_edges",
+    "get_edges_df",
+    "get_graph",
+]
+
+
+def get_graph(prefix: str, **kwargs: Unpack[GetOntologyKwargs]) -> nx.DiGraph:
+    """Get the relation graph."""
+    rv = nx.MultiDiGraph()
+    for s in get_ids(prefix, **kwargs):
+        rv.add_node(f"{prefix}:{s}")
+    df = get_edges_df(prefix=prefix, **kwargs)
+    for s, p, o in df.values:
+        rv.add_edge(s, p, key=o)
+    return rv
+
+
+def get_edges_df(prefix, **kwargs: Unpack[GetOntologyKwargs]) -> pd.DataFrame:
+    """Get a dataframe of edges triples."""
+    version = get_version_from_kwargs(prefix, kwargs)
+    path = get_cache_path(prefix, CacheArtifact.edges, version=version)
+
+    @cached_df(
+        path=path, dtype=str, force=check_should_force(kwargs), cache=check_should_cache(kwargs)
+    )
+    def _df_getter() -> pd.DataFrame:
+        return get_ontology(prefix, **kwargs).get_edges_df(use_tqdm=check_should_use_tqdm(kwargs))
+
+    return _df_getter()
+
+
+def get_edges(
+    prefix, **kwargs: Unpack[GetOntologyKwargs]
+) -> list[tuple[Reference, Reference, Reference]]:
+    """Get a list of edge triples."""
+    df = get_edges_df(prefix, **kwargs)
+    return [
+        (Reference.from_curie(s), Reference.from_curie(p), Reference.from_curie(o))
+        for s, p, o in tqdm(
+            df.values,
+            desc=f"[{prefix}] parsing edges",
+            unit="edge",
+            unit_scale=True,
+            disable=not check_should_use_tqdm(kwargs),
+        )
+    ]