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

pyobo/sources/geonames/utils.py

@@ -0,0 +1,115 @@
+"""Shared code for geonames sources."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import pandas as pd
+from tqdm import tqdm
+
+from pyobo import Reference, Term, TypeDef, default_reference
+from pyobo.struct.struct import CHARLIE_TERM, HUMAN_TERM, PYOBO_INJECTED
+from pyobo.utils.path import ensure_df
+
+PREFIX = "geonames"
+PREFIX_FEATURE = "geonames.feature"
+
+FEATURES_URL = "https://download.geonames.org/export/dump/featureCodes_en.txt"
+COUNTRIES_URL = "https://download.geonames.org/export/dump/countryInfo.txt"
+ADMIN1_URL = "https://download.geonames.org/export/dump/admin1CodesASCII.txt"
+ADMIN2_URL = "https://download.geonames.org/export/dump/admin2Codes.txt"
+CITIES_URL = "https://download.geonames.org/export/dump/cities15000.zip"
+SYNONYMS_URL = "https://download.geonames.org/export/dump/alternateNamesV2.zip"
+
+# External parent classes
+CITY = Reference(prefix="ENVO", identifier="00000856", name="city")
+NATION = Reference(prefix="ENVO", identifier="00000009", name="national geopolitical entity")
+ADMIN_1 = Reference(prefix="ENVO", identifier="00000005", name="first-order administrative region")
+ADMIN_2 = Reference(prefix="ENVO", identifier="00000006", name="second-order administrative region")
+
+# Builtin classes
+FEATURE = default_reference(PREFIX_FEATURE, "feature", "GeoNames feature")
+FEATURE_TERM = Term(reference=FEATURE)
+
+# Type definitions
+CODE_TYPEDEF = TypeDef(
+    reference=default_reference(PREFIX, "code", name="GeoNames code"), is_metadata_tag=True
+)
+
+SYNONYMS_DF_COLUMNS = [
+    "id",
+    "geonames_id",
+    "iso_lang",
+    "synonym",
+    "is_preferred",
+    "is_short",
+    "is_colloquial",
+    "is_historic",
+    "start_time",
+    "end_time",
+]
+
+P_CATEGORY = default_reference(PREFIX_FEATURE, "P", "city feature")
+
+FEATURE_CATEGORIES = {
+    "A": default_reference(PREFIX_FEATURE, "A", "geopolitical feature"),
+    "H": default_reference(PREFIX_FEATURE, "H", "aquatic feature"),
+    "V": default_reference(PREFIX_FEATURE, "V", "floral feature feature"),
+    "S": default_reference(PREFIX_FEATURE, "S", "building feature"),
+    "U": default_reference(PREFIX_FEATURE, "U", "undersea feature"),
+    "T": default_reference(PREFIX_FEATURE, "T", "geographic feature"),
+    "L": default_reference(PREFIX_FEATURE, "L", "parks feature"),
+    "P": P_CATEGORY,
+    "R": default_reference(PREFIX_FEATURE, "R", "road or rail feature"),
+}
+
+
+def get_features(*, force: bool = False) -> dict[str, Term]:
+    """Get all features."""
+    df = ensure_df(
+        PREFIX,
+        url=FEATURES_URL,
+        force=force,
+        keep_default_na=False,  # NA is a country code
+        dtype=str,
+    )
+    rv = {}
+    for identifier, name, description in df.values:
+        if pd.isna(identifier) or identifier == "null":
+            continue
+
+        term = Term(
+            reference=Reference(
+                prefix=PREFIX_FEATURE, identifier=identifier, name=name if pd.notna(name) else None
+            ),
+            definition=description if pd.notna(description) else None,
+        )
+        parent_letter, _, rest = identifier.partition(".")
+        if not rest:
+            tqdm.write(f"[{PREFIX_FEATURE}] unhandled identifier: {identifier}")
+        elif parent_letter not in FEATURE_CATEGORIES:
+            tqdm.write(f"[{PREFIX_FEATURE}] unhandled category: {parent_letter}")
+        else:
+            term.append_parent(FEATURE_CATEGORIES[parent_letter])
+
+        rv[identifier] = term
+    return rv
+
+
+def get_feature_terms(
+    force: bool = False, features: dict[str, Term] | None = None
+) -> Iterable[Term]:
+    """Get terms for GeoNames features."""
+    yield FEATURE_TERM
+    yield HUMAN_TERM
+    yield CHARLIE_TERM
+    for cat in FEATURE_CATEGORIES.values():
+        yield (
+            Term(reference=cat)
+            .append_parent(FEATURE_TERM)
+            .append_contributor(CHARLIE_TERM)
+            .append_comment(PYOBO_INJECTED)
+        )
+    if features is None:
+        features = get_features(force=force)
+    yield from features.values()

pyobo/sources/gmt_utils.py

@@ -2,17 +2,17 @@
 
 from collections.abc import Iterable
 from pathlib import Path
-from typing import Union
 
 GMTSummary = tuple[str, str, set[str]]
 WikiPathwaysGMTSummary = tuple[str, str, str, str, str, set[str]]
 
 
-def parse_gmt_file(path: Union[str, Path]) -> Iterable[GMTSummary]:
+def parse_gmt_file(path: str | Path) -> Iterable[GMTSummary]:
     """Return file as list of pathway - gene sets (ENTREZ-identifiers).
 
     :param path: path to GMT file
-    :return: line-based processed file
+
+    :yields: processed lines
     """
     with open(path) as file:
         for line in file:
@@ -23,15 +23,14 @@ def _process_line(line: str) -> tuple[str, str, set[str]]:
     """Return the pathway name, url, and gene sets associated.
 
     :param line: gmt file line
-    :return: pathway name
-    :return: pathway info url
-    :return: genes set associated
+
+    :returns: pathway name, pathway info url, and genes set associated
     """
     name, info, *entries = (p.strip() for p in line.split("\t"))
     return name, info, set(entries)
 
 
-def parse_wikipathways_gmt(path: Union[str, Path]) -> Iterable[WikiPathwaysGMTSummary]:
+def parse_wikipathways_gmt(path: str | Path) -> Iterable[WikiPathwaysGMTSummary]:
     """Parse WikiPathways GMT."""
     for info, _uri, entries in parse_gmt_file(path):
         info, version, identifier, species = info.split("%")

pyobo/sources/go.py

@@ -4,33 +4,46 @@ from pyobo import get_descendants
 
 __all__ = [
     "is_biological_process",
-    "is_molecular_function",
     "is_cellular_component",
+    "is_molecular_function",
 ]
 
 
 def is_biological_process(identifier: str) -> bool:
     """Return if the given GO identifier is a biological process.
 
+    :param identifier: A local unique identifier from GO
+    :return: If the identifier is a biological process
+
     >>> is_biological_process("0006915")
     True
     >>> is_biological_process("GO:0006915")
     True
-    >>> is_molecular_function("0006915")
-    False
-    >>> is_cellular_component("0006915")
-    False
     """
     return _is_descendant(identifier, "0008150")
 
 
 def is_molecular_function(identifier: str) -> bool:
-    """Return if the given GO identifier is a molecular function."""
+    """Return if the given GO identifier is a molecular function.
+
+    :param identifier: A local unique identifier from GO
+    :return: If the identifier is a molecular function
+
+    >>> is_molecular_function("0006915")
+    False
+    """
     return _is_descendant(identifier, "0003674")
 
 
 def is_cellular_component(identifier: str) -> bool:
-    """Return if the given GO identifier is a cellular component."""
+    """Return if the given GO identifier is a cellular component.
+
+    :param identifier: A local unique identifier from GO
+    :return: If the identifier is a cellular component
+
+    >>> is_cellular_component("0006915")
+    False
+    """
     return _is_descendant(identifier, "0005575")
 
 
@@ -40,9 +53,3 @@ def _is_descendant(identifier: str, ancestor: str) -> bool:
         identifier = f"go:{identifier}"
     descendants = get_descendants("go", ancestor)
     return descendants is not None and identifier in descendants
-
-
-if __name__ == "__main__":
-    import doctest
-
-    doctest.testmod()

pyobo/sources/gtdb.py

@@ -0,0 +1,154 @@
+"""Convert GTDB taxonomy to OBO format."""
+
+import logging
+from collections.abc import Iterable
+
+import pandas as pd
+from tqdm.auto import tqdm
+
+from pyobo.struct import Obo, Reference, Term
+from pyobo.struct.typedef import has_taxonomy_rank
+from pyobo.utils.path import ensure_path
+
+__all__ = [
+    "GTDBGetter",
+]
+
+PREFIX = "gtdb"
+
+#: A mapping from GTDB prefixes to TAXRANK ranks
+LEVEL_TO_TAXRANK = {
+    "d": Reference(prefix="TAXRANK", identifier="0000037", name="domain"),
+    "p": Reference(prefix="TAXRANK", identifier="0000001", name="phylum"),
+    "c": Reference(prefix="TAXRANK", identifier="0000002", name="class"),
+    "o": Reference(prefix="TAXRANK", identifier="0000003", name="order"),
+    "f": Reference(prefix="TAXRANK", identifier="0000004", name="family"),
+    "g": Reference(prefix="TAXRANK", identifier="0000005", name="genus"),
+    "s": Reference(prefix="TAXRANK", identifier="0000006", name="species"),
+}
+
+#: AR stands for archea
+GTDB_AR_URL = "https://data.gtdb.ecogenomic.org/releases/latest/ar53_metadata.tsv.gz"
+#: BAC stands for bacteria
+GTDB_BAC_URL = "https://data.gtdb.ecogenomic.org/releases/latest/bac120_metadata.tsv.gz"
+
+logger = logging.getLogger(__name__)
+
+
+class GTDBGetter(Obo):
+    """An ontology representation of the GTDB taxonomy."""
+
+    ontology = bioversions_key = PREFIX
+    typedefs = [has_taxonomy_rank]
+    root_terms = [
+        Reference(prefix=PREFIX, identifier="d__Archea", name="Archea"),
+        Reference(prefix=PREFIX, identifier="d__Bacteria", name="Bacteria"),
+    ]
+
+    def iter_terms(self, force: bool = False) -> Iterable[Term]:
+        """Iterate over terms in the ontology."""
+        return iter_terms(version=self._version_or_raise, force=force)
+
+
+def iter_terms(version: str, force: bool = False) -> Iterable[Term]:
+    """Iterate over GTDB terms."""
+    # Add the taxrank terms so we get nice display in Protege
+    for reference in LEVEL_TO_TAXRANK.values():
+        yield Term(reference=reference)
+
+    ar_path = ensure_path(PREFIX, url=GTDB_AR_URL, version=version, force=force)
+    bac_path = ensure_path(PREFIX, url=GTDB_BAC_URL, version=version, force=force)
+    columns = ["gtdb_taxonomy", "ncbi_species_taxid"]
+    for path_name, path in [
+        ("ar", ar_path),
+        ("bac", bac_path),
+    ]:
+        df = pd.read_csv(path, sep="\t", dtype=str)
+        for tax_string, ncbitaxon_id in tqdm(
+            df[columns].values, desc=f"[{PREFIX}] processing {path_name}", unit_scale=True
+        ):
+            yield from _process_row(tax_string, ncbitaxon_id)
+
+
+def _process_row(tax_string, ncbitaxon_id) -> Iterable[Term]:
+    if not isinstance(tax_string, str):
+        logger.warning(f"Invalid taxonomy string: {tax_string}")
+        return None
+
+    taxa = _parse_tax_string(tax_string)
+    if not taxa:
+        logger.warning(f"No valid taxa found in: {tax_string}")
+        return None
+
+    parent_reference = None
+    for level, name in taxa:
+        identifier = f"{level}__{name.replace(' ', '_')}"
+        term = Term(
+            reference=Reference(prefix=PREFIX, identifier=identifier, name=name),
+        )
+        term.annotate_object(has_taxonomy_rank, LEVEL_TO_TAXRANK[level])
+
+        if parent_reference:
+            term.append_parent(parent_reference)
+        if ncbitaxon_id and level == "s":
+            # if the level is "s", it's a species. There might be multiple
+            # mappings to NCBITaxon, so we only use "see also" as the predicate
+            term.append_xref(
+                Reference(prefix="ncbitaxon", identifier=ncbitaxon_id),
+                # TODO @jose use confidence=... keyword here
+            )
+
+        yield term
+        parent_reference = term.reference
+
+
+def _parse_tax_string(tax_string: str) -> list[tuple[str, str]]:
+    """Parse GTDB taxonomy string into (level, name) tuples."""
+    return [
+        level_name for part in _split_tax_string(tax_string) if (level_name := _parse_name(part))
+    ]
+
+
+def _split_tax_string(tax_string: str) -> list[str]:
+    return [p.strip() for p in tax_string.split(";") if p.strip()]
+
+
+def _parse_name(part: str) -> tuple[str, str] | None:
+    """Parse a GTDB taxonomy identifier.
+
+    :param part: The string
+    :returns: A tuple with the level and name, if parsable
+
+    >>> _parse_name("f__Sulfolobaceae")
+    ('f', 'Sulfoobaceae')
+
+    The following is malformed because it is missing a double underscore
+
+    >>> _parse_name("f_Sulfolobaceae")
+
+    The following is malformed because it has an invalid taxonomic level
+
+    >>> _parse_name("x__Sulfolobaceae")
+
+    The following is malformed because it's missing a name
+
+    >>> _parse_name("f__")
+    """
+    if len(part) < 4 or "__" not in part:
+        logger.warning(f"Malformed taxon string: {part}")
+        return None
+    level, delimiter, name = part.partition("__")
+    if not delimiter:
+        logger.warning(f"Missing double underscore delimiter: {part}")
+        return None
+    if level not in LEVEL_TO_TAXRANK or not name:
+        logger.warning(f"Invalid taxonomic level `{level}` in {part}")
+        return None
+    if not name:
+        logger.warning(f"Missing name: {part}")
+        return None
+    return level, name
+
+
+if __name__ == "__main__":
+    GTDBGetter().cli()

pyobo/sources/gwascentral/__init__.py

@@ -0,0 +1,9 @@
+"""Resources from GWAS Central."""
+
+from .gwascentral_phenotype import GWASCentralPhenotypeGetter
+from .gwascentral_study import GWASCentralStudyGetter
+
+__all__ = [
+    "GWASCentralPhenotypeGetter",
+    "GWASCentralStudyGetter",
+]

pyobo/sources/{gwascentral_phenotype.py → gwascentral/gwascentral_phenotype.py}

@@ -5,10 +5,11 @@ from collections.abc import Iterable
 
 from tqdm.auto import tqdm, trange
 
-from pyobo.sources.gwascentral_study import VERSION
 from pyobo.struct import Obo, Reference, Term
 from pyobo.utils.path import ensure_path
 
+from .gwascentral_study import VERSION
+
 __all__ = [
     "GWASCentralPhenotypeGetter",
 ]
@@ -27,11 +28,6 @@ class GWASCentralPhenotypeGetter(Obo):
         return iter_terms(force=force, version=self._version_or_raise)
 
 
-def get_obo(force: bool = False) -> Obo:
-    """Get GWAS Central Studies as OBO."""
-    return GWASCentralPhenotypeGetter(force=force)
-
-
 def iter_terms(version: str, force: bool = False) -> Iterable[Term]:
     """Iterate over terms from GWAS Central Phenotype."""
     for n in trange(1, 11000, desc=f"{PREFIX} download"):
@@ -43,11 +39,13 @@ def iter_terms(version: str, force: bool = False) -> Iterable[Term]:
                 url=f"https://www.gwascentral.org/phenotype/HGVPM{n}?format=json",
                 name=f"HGVPM{n}.json",
                 force=force,
+                backend="requests",
+                timeout=1,
             )
         except OSError as e:
             tqdm.write(f"{n}: {e}")
             continue
-        with open(path) as file:
+        with path.open() as file:
             j = json.load(file)
 
         description = j.get("description")

pyobo/sources/{gwascentral_study.py → gwascentral/gwascentral_study.py}

@@ -3,7 +3,6 @@
 import logging
 import tarfile
 from collections.abc import Iterable
-from typing import Optional
 from xml.etree import ElementTree
 
 from pyobo.struct import Obo, Reference, Term, has_part
@@ -31,12 +30,7 @@ class GWASCentralStudyGetter(Obo):
         return iterate_terms(force=force, version=self._version_or_raise)
 
 
-def get_obo(force: bool = False):
-    """Get GWAS Central Studies as OBO."""
-    return GWASCentralStudyGetter(force=force)
-
-
-def _find_text(element, name: str) -> Optional[str]:
+def _find_text(element, name: str) -> str | None:
     x = element.find(name)
     if x is not None:
         return x.text

pyobo/sources/hgnc/__init__.py

@@ -0,0 +1,9 @@
+"""Resources from HGNC."""
+
+from .hgnc import HGNCGetter
+from .hgncgenefamily import HGNCGroupGetter
+
+__all__ = [
+    "HGNCGetter",
+    "HGNCGroupGetter",
+]