pyobo 0.12.7__py3-none-any.whl → 0.12.9__py3-none-any.whl

pyobo/__init__.py

@@ -50,6 +50,7 @@ from .api import (
     get_synonyms,
     get_text_embedding,
     get_text_embedding_similarity,
+    get_text_embeddings_df,
     get_typedef_df,
     get_xref,
     get_xrefs,
@@ -58,7 +59,13 @@ from .api import (
     is_descendent,
 )
 from .getters import get_ontology
-from .ner import get_grounder, ground
+from .ner import (
+    get_grounder,
+    get_scispacy_entities,
+    get_scispacy_entity_linker,
+    get_scispacy_knowledgebase,
+    ground,
+)
 from .plugins import (
     has_nomenclature_plugin,
     iter_nomenclature_plugins,
@@ -139,12 +146,16 @@ __all__ = [
     "get_relation",
     "get_relation_mapping",
     "get_relations_df",
+    "get_scispacy_entities",
+    "get_scispacy_entity_linker",
+    "get_scispacy_knowledgebase",
     "get_species",
     "get_sssom_df",
     "get_subhierarchy",
     "get_synonyms",
     "get_text_embedding",
     "get_text_embedding_similarity",
+    "get_text_embeddings_df",
     "get_typedef_df",
     "get_version",
     "get_xref",

pyobo/api/__init__.py

@@ -8,7 +8,7 @@ from .alts import (
 )
 from .combine import get_literal_mappings_subset
 from .edges import get_edges, get_edges_df, get_graph
-from .embedding import get_text_embedding, get_text_embedding_similarity
+from .embedding import get_text_embedding, get_text_embedding_similarity, get_text_embeddings_df
 from .hierarchy import (
     get_ancestors,
     get_children,
@@ -119,6 +119,7 @@ __all__ = [
     "get_synonyms",
     "get_text_embedding",
     "get_text_embedding_similarity",
+    "get_text_embeddings_df",
     "get_typedef_df",
     "get_version",
     "get_xref",

pyobo/api/embedding.py

@@ -6,8 +6,9 @@ from typing import TYPE_CHECKING
 
 import curies
 import numpy as np
+import pandas as pd
 
-from pyobo.api.names import get_definition, get_name
+from pyobo.api.names import get_definition, get_name, get_references
 
 if TYPE_CHECKING:
     import sentence_transformers
@@ -16,6 +17,7 @@ __all__ = [
     "get_text_embedding",
     "get_text_embedding_model",
     "get_text_embedding_similarity",
+    "get_text_embeddings_df",
 ]
 
 
@@ -39,6 +41,30 @@ def _get_text(
     return name
 
 
+def get_text_embeddings_df(
+    prefix: str,
+    *,
+    model: sentence_transformers.SentenceTransformer | None = None,
+) -> pd.DataFrame:
+    """Get embeddings for all entities in the resource.
+
+    :param prefix: A reference, either as a string or Reference object
+    :param model: A sentence transformer model. Defaults to ``all-MiniLM-L6-v2`` if not
+        given.
+    """
+    luids, texts = [], []
+    for reference in get_references(prefix):
+        text = _get_text(reference)
+        if text is None:
+            continue
+        luids.append(reference.identifier)
+        texts.append(text)
+    if model is None:
+        model = get_text_embedding_model()
+    res = model.encode(texts)
+    return pd.DataFrame(res, index=luids)
+
+
 def get_text_embedding(
     reference: str | curies.Reference | curies.ReferenceTuple,
     *,
@@ -47,8 +73,10 @@ def get_text_embedding(
     """Get a text embedding for an entity, or return none if no text is available.
 
     :param reference: A reference, either as a string or Reference object
-    :param model: A sentence transformer model. Defaults to ``all-MiniLM-L6-v2`` if not given.
-    :return: A 1D numpy float array of embeddings from :class:`sentence_transformers`
+    :param model: A sentence transformer model. Defaults to ``all-MiniLM-L6-v2`` if not
+        given.
+
+    :returns: A 1D numpy float array of embeddings from :class:`sentence_transformers`
 
     .. code-block:: python
 
@@ -87,9 +115,11 @@ def get_text_embedding_similarity(
 
     :param reference_1: A reference, given as a string or Reference object
     :param reference_2: A second reference
-    :param model: A sentence transformer model. Defaults to ``all-MiniLM-L6-v2`` if not given.
-    :returns:
-        A floating point similarity, if text is available for both references, otherwise none
+    :param model: A sentence transformer model. Defaults to ``all-MiniLM-L6-v2`` if not
+        given.
+
+    :returns: A floating point similarity, if text is available for both references,
+        otherwise none
 
     .. code-block:: python
 

pyobo/api/hierarchy.py

@@ -163,7 +163,8 @@ def is_descendent(
     :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
+
+    :returns: If the decendant has the given ancestor
 
     Check that ``GO:0070246`` (natural killer cell apoptotic process) is a descendant of
     ``GO:0006915`` (apoptotic process)
@@ -254,10 +255,11 @@ def has_ancestor(
     :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):
+    :returns: 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")

pyobo/api/properties.py

@@ -111,6 +111,7 @@ def get_properties_df(prefix: str, **kwargs: Unpack[GetOntologyKwargs]) -> pd.Da
     """Extract properties.
 
     :param prefix: the resource to load
+
     :returns: A dataframe with the properties
     """
     df1 = get_literal_properties_df(prefix, **kwargs)
@@ -131,6 +132,7 @@ def get_filtered_properties_mapping(
 
     :param prefix: the resource to load
     :param prop: the property to extract
+
     :returns: A mapping from identifier to property value
     """
     df = get_filtered_properties_df(prefix, prop, **kwargs)
@@ -145,6 +147,7 @@ def get_filtered_properties_multimapping(
 
     :param prefix: the resource to load
     :param prop: the property to extract
+
     :returns: A mapping from identifier to property values
     """
     df = get_filtered_properties_df(prefix, prop, **kwargs)
@@ -159,7 +162,9 @@ def get_property(
     :param prefix: the resource to load
     :param identifier: the identifier withing the resource
     :param prop: the property to extract
-    :returns: The single value for the property. If multiple are expected, use :func:`get_properties`
+
+    :returns: The single value for the property. If multiple are expected, use
+        :func:`get_properties`
 
     >>> import pyobo
     >>> pyobo.get_property("chebi", "132964", "http://purl.obolibrary.org/obo/chebi/smiles")
@@ -182,7 +187,9 @@ def get_properties(
     :param prefix: the resource to load
     :param identifier: the identifier withing the resource
     :param prop: the property to extract
-    :returns: Multiple values for the property. If only one is expected, use :func:`get_property`
+
+    :returns: Multiple values for the property. If only one is expected, use
+        :func:`get_property`
     """
     filtered_properties_multimapping = get_filtered_properties_multimapping(
         prefix=prefix, prop=prop, **kwargs
@@ -198,7 +205,9 @@ def get_filtered_properties_df(
 
     :param prefix: the resource to load
     :param prop: the property to extract
-    :returns: A dataframe from identifier to property value. Columns are [<prefix>_id, value].
+
+    :returns: A dataframe from identifier to property value. Columns are [<prefix>_id,
+        value].
     """
     prop = _ensure_ref(prop, ontology_prefix=prefix)
     df = get_properties_df(prefix, **kwargs)

pyobo/api/relations.py

@@ -135,9 +135,11 @@ def get_relation_mapping(
 ) -> Mapping[str, str]:
     """Get relations from identifiers in the source prefix to target prefix with the given relation.
 
-    .. warning:: Assumes there's only one version of the property for each term.
+    .. warning::
 
-     Example usage: get homology between HGNC and MGI:
+        Assumes there's only one version of the property for each term.
+
+    Example usage: get homology between HGNC and MGI:
 
     >>> import pyobo
     >>> human_mapt_hgnc_id = "6893"
@@ -161,16 +163,18 @@ def get_relation(
 ) -> str | None:
     """Get the target identifier corresponding to the given relationship from the source prefix/identifier pair.
 
-    .. warning:: Assumes there's only one version of the property for each term.
+    .. warning::
+
+        Assumes there's only one version of the property for each term.
 
-     Example usage: get homology between MAPT in HGNC and MGI:
+    Example usage: get homology between MAPT in HGNC and MGI:
 
     >>> import pyobo
     >>> human_mapt_hgnc_id = "6893"
     >>> mouse_mapt_mgi_id = "97180"
     >>> assert mouse_mapt_mgi_id == pyobo.get_relation(
     ...     "hgnc", human_mapt_hgnc_id, "ro:HOM0000017", "mgi"
-    ... )
+    >>> )
     """
     relation_mapping = get_relation_mapping(
         prefix=prefix,

pyobo/ner/__init__.py

@@ -2,8 +2,16 @@
 
 from .api import get_grounder
 from .normalizer import ground
+from .scispacy_utils import (
+    get_scispacy_entities,
+    get_scispacy_entity_linker,
+    get_scispacy_knowledgebase,
+)
 
 __all__ = [
     "get_grounder",
+    "get_scispacy_entities",
+    "get_scispacy_entity_linker",
+    "get_scispacy_knowledgebase",
     "ground",
 ]

pyobo/ner/normalizer.py

@@ -20,8 +20,8 @@ def ground(
 ) -> Reference | None:
     """Normalize a string given the prefix's labels and synonyms.
 
-    :param prefix: If a string, only grounds against that namespace. If a list, will try grounding
-        against all in that order
+    :param prefix: If a string, only grounds against that namespace. If a list, will try
+        grounding against all in that order
     :param query: The string to try grounding
     """
     grounder = get_grounder(prefix, **kwargs)

pyobo/ner/scispacy_utils.py

@@ -0,0 +1,241 @@
+"""A bridge between PyOBO and :mod:`scispacy`.
+
+:mod:`scispacy` implements a lexical index in
+:class:`scispacy.linking_utils.KnowledgeBase` which keeps track of labels, synonyms, and
+definitions for entities. These are used to construct a TF-IDF index and implement
+entity linking (also called named entity normalization (NEN) or grounding) in
+:class:`scispacy.linking.EntityLinker`.
+
+Constructing a Lexical Index
+============================
+
+An *ad hoc* SciSpacy lexical index can be constructed on-the-fly by passing a
+Bioregistry prefix to :func:`pyobo.get_scispacy_knowledgebase`. In the following
+example, the prefix ``to`` is used to construct a lexical index for the `Plant Trait
+Ontology <https://bioregistry.io/to>`_.
+
+.. code-block:: python
+
+    import pyobo
+    from scispacy.linking_utils import KnowledgeBase
+
+    kb: KnowledgeBase = pyobo.get_scispacy_knowledgebase("to")
+
+The high-level PyOBO interface abstracts the differences between external ontologies
+like the Plant Trait Ontology and databases that are converted to ontologies in
+:mod:`pyobo.sources` like the `HUGO Gene Nomenclature Committee
+<https://bioregistry.io/hgnc>`_. Therefore, you can also do
+
+.. code-block:: python
+
+    import pyobo
+    from scispacy.linking_utils import KnowledgeBase
+
+    kb: KnowledgeBase = pyobo.get_scispacy_knowledgebase("hgnc")
+
+Alternatively, a reusable class can be defined like in the following:
+
+.. code-block:: python
+
+    import pyobo
+    from scispacy.linking_utils import KnowledgeBase
+
+
+    class HGNCKnowledgeBase(KnowledgeBase):
+        def __init__(self) -> None:
+            super().__init__(pyobo.get_scispacy_entities("hgnc"))
+
+
+    kb = HGNCKnowledgeBase()
+
+Constructing an Entity Linker
+=============================
+
+An entity linker can be constructed from a :class:`scispacy.linking_utils.KnowledgeBase`
+like in:
+
+.. code-block:: python
+
+    import pyobo
+    from scispacy.linking import EntityLinker
+
+    kb = pyobo.get_scispacy_knowledgebase("hgnc")
+    linker = EntityLinker.from_kb(kb, filter_for_definitions=False)
+
+Where ``filter_for_definitions`` is set to ``False`` to retain entities that don't have
+a definition.
+
+PyOBO provides a convenience function :func:`pyobo.get_scispacy_entity_linker` that
+wraps this workflow and also automatically caches the TF-IDF index constructed in the
+process in the correctly versioned folder in the PyOBO cache.
+
+.. code-block:: python
+
+    import pyobo
+    from scispacy.linking import EntityLinker
+
+    linker = pyobo.get_scispacy_entity_linker("hgnc", filter_for_definitions=False)
+
+Full Workflow
+=============
+
+Once an entity linker has been constructed, it can b used in series with a
+:mod:`spacy.Language` object instantiated with :func:`spacy.load` to ground named
+entities that were recognized by a model like ``en_core_web_sm``
+
+.. code-block:: python
+
+    import pyobo
+    import spacy
+    from scispacy.linking import EntityLinker
+    from tabulate import tabulate
+
+    linker: EntityLinker = pyobo.get_scispacy_entity_linker("hgnc", filter_for_definitions=False)
+
+    # now, put it all together with a NER model
+    nlp = spacy.load("en_core_web_sm")
+
+    text = (
+        "RAC(Rho family)-alpha serine/threonine-protein kinase "
+        "is an enzyme that in humans is encoded by the AKT1 gene."
+    )
+    doc = linker(nlp(text))
+
+    rows = [
+        (
+            span,
+            span.start_char,
+            span.end_char,
+            f"`{curie} <https://bioregistry.io/{curie}>`_",
+            score,
+        )
+        for span in doc.ents
+        for curie, score in span._.kb_ents
+    ]
+    print(tabulate(rows, headers=["text", "start", "end", "prefix", "identifier"], tablefmt="rst"))
+
+==== ===== === ============================================= ========
+text start end curie                                         score
+==== ===== === ============================================= ========
+AKT1 100   104 `hgnc:391 <https://bioregistry.io/hgnc:391>`_ 1
+AKT1 100   104 `hgnc:392 <https://bioregistry.io/hgnc:392>`_ 0.776504
+AKT1 100   104 `hgnc:393 <https://bioregistry.io/hgnc:393>`_ 0.764049
+==== ===== === ============================================= ========
+
+This example recognizes the AKT serine/threonine kinase 1 (AKT1) gene and provides three
+highly scored groundings, the best of which, `hgnc:391
+<https://bioregistry.io/hgnc:391>`_, is correct.
+
+.. note::
+
+    The groundings and scores are stored by SciSpacy in the hidden attribute
+    ``span._.kb_ents``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any
+
+from typing_extensions import Unpack
+
+from ..api.utils import get_version_from_kwargs
+from ..constants import GetOntologyKwargs
+from ..getters import get_ontology
+from ..utils.path import prefix_directory_join
+
+if TYPE_CHECKING:
+    from scispacy.linking import EntityLinker
+    from scispacy.linking_utils import Entity, KnowledgeBase
+
+__all__ = [
+    "get_scispacy_entities",
+    "get_scispacy_entity_linker",
+    "get_scispacy_knowledgebase",
+]
+
+
+def get_scispacy_entity_linker(
+    prefix: str,
+    *,
+    ontology_kwargs: GetOntologyKwargs | None = None,
+    candidate_generator_kwargs: dict[str, Any] | None = None,
+    **entity_linker_kwargs: Any,
+) -> EntityLinker:
+    """Get a knowledgebase object for usage with :mod:`scispacy`.
+
+    :param prefix :
+        The ontology's prefix, such as ``go` for Gene Ontology, ``doid`` for the Disease
+        Ontology, or more.
+
+    :param ontology_kwargs: keyword arguments to pass to :func:`pyobo.get_ontology`,
+        such as ``version``.
+    :param candidate_generator_kwargs: keyword arguments to pass to
+        :class:`scispacy.candidate_generation.CandidateGenerator`, such as ``ef_search``
+    :param entity_linker_kwargs: keyword arguments to pass to
+        :class:`scispacy.linking.EntityLinker`, such as ``ef_search``
+
+    :returns: An object that can be applied in a :mod:`spacy` natural language
+        processing workflow, namely to apply grounding/named entity normalization to
+        recognized named entities.
+    """
+    from scispacy.linking import EntityLinker
+
+    if ontology_kwargs is None:
+        ontology_kwargs = {}
+
+    version = get_version_from_kwargs(prefix, ontology_kwargs)
+    scispacy_cache_directory = prefix_directory_join(prefix, "scispacy", version=version)
+
+    # TODO see if we can skip loading the KB
+    kb = get_scispacy_knowledgebase(prefix, **ontology_kwargs)
+    linker = EntityLinker.from_kb(
+        kb,
+        ann_index_out_dir=scispacy_cache_directory.as_posix(),
+        candidate_generator_kwargs=candidate_generator_kwargs,
+        **(entity_linker_kwargs or {}),
+    )
+    return linker
+
+
+def get_scispacy_knowledgebase(prefix: str, **kwargs: Unpack[GetOntologyKwargs]) -> KnowledgeBase:
+    """Get a knowledgebase object for usage with :mod:`scispacy`.
+
+    :param prefix :
+        The ontology's prefix, such as ``go` for Gene Ontology, ``doid`` for the Disease
+        Ontology, or more.
+
+    :param kwargs :
+        keyword arguments to pass to :func:`pyobo.get_ontology`, such as ``version``.
+
+    :returns: An object that represents a lexical index over name, synonym, and
+        definition strings from the ontology.
+    """
+    from scispacy.linking_utils import KnowledgeBase
+
+    return KnowledgeBase(get_scispacy_entities(prefix, **kwargs))
+
+
+def get_scispacy_entities(prefix: str, **kwargs: Unpack[GetOntologyKwargs]) -> Iterable[Entity]:
+    """Iterate over entities in a given ontology via :mod:`pyobo`.
+
+    :param prefix :
+        The ontology's prefix, such as ``go` for Gene Ontology, ``doid`` for the Disease
+        Ontology, or more.
+
+    :param kwargs :
+        keyword arguments to pass to :func:`pyobo.get_ontology`, such as ``version``.
+
+    :yields: Entity objects for all terms in the ontology
+    """
+    from scispacy.linking_utils import Entity
+
+    # TODO reuse labels, synonyms, and definitions cache
+    ontology = get_ontology(prefix, **kwargs)
+    for term in ontology:
+        yield Entity(
+            concept_id=term.curie,
+            canonical_name=term.name,
+            aliases=[s.name for s in term.synonyms],
+            definition=term.definition,
+        )

pyobo/sources/__init__.py

@@ -34,6 +34,7 @@ from .gwascentral import GWASCentralPhenotypeGetter, GWASCentralStudyGetter
 from .hgnc import HGNCGetter, HGNCGroupGetter
 from .iana_media_type import IANAGetter
 from .icd import ICD10Getter, ICD11Getter
+from .iconclass import IconclassGetter
 from .intact import IntactGetter
 from .interpro import InterProGetter
 from .itis import ITISGetter
@@ -115,6 +116,7 @@ __all__ = [
     "ICD10Getter",
     "ICD11Getter",
     "ITISGetter",
+    "IconclassGetter",
     "IntactGetter",
     "InterProGetter",
     "KEGGGeneGetter",