metahq-core 0.1.1__py3-none-any.whl → 1.0.0rc1__py3-none-any.whl

metahq_core/{ontology/loader.py → relations_loader.py}

@@ -20,6 +20,7 @@ from pathlib import Path
 import polars as pl
 
 from metahq_core.logger import setup_logger
+from metahq_core.util.supported import get_default_log_dir
 
 # these are used a lot so defining them as constants to
 # make them easy to change later.
@@ -35,7 +36,7 @@ class RelationsLoader:
 
     """
 
-    def __init__(self, file, logger=None, loglevel=20, logdir=Path(".")):
+    def __init__(self, file, logger=None, loglevel=20, logdir=get_default_log_dir()):
         self.relations: pl.LazyFrame = self.setup(file)
 
         if logger is None:

metahq_core/search.py

@@ -25,6 +25,8 @@ but the current implementation is IMHO a reasonable starting point.
 
 Author: Faisal Alquaddoomi
 Date: 2025-09-25
+
+Last updated: 2025-11-28 by Parker Hicks
 """
 
 from __future__ import annotations
@@ -60,13 +62,21 @@ DEFAULT_SCOPE = "RELATED"
 
 
 class SynonymEntry(TypedDict):
+    """Storage of synonyms and their scope.
+
+    Attributes:
+        text (str):
+            Any piece of text.
+        scope (NotRequired[Literal["EXACT", "NARROW", "BROAD", "RELATED"]]):
+            The importance of `text`.
+    """
+
     text: str
     scope: NotRequired[Literal["EXACT", "NARROW", "BROAD", "RELATED"]]
 
 
 def doc_text_for(name: str, syns: list[SynonymEntry]) -> str:
-    """
-    Build the doc_text column for BM25 indexing from the name and synonyms.
+    """Build the doc_text column for BM25 indexing from the name and synonyms.
 
     See the NAME_WEIGHT and SCOPE_WEIGHTS constants for how parts of the record
     are weighted in the resulting document.
@@ -74,9 +84,14 @@ def doc_text_for(name: str, syns: list[SynonymEntry]) -> str:
     Per the OBO 1.4 spec, synonyms can have scopes in {EXACT, BROAD, NARROW,
     RELATED}. If no scope is given, it is treated as RELATED.
 
-    :param name: The primary name of the term.
-    :param syns: List of {"text": str, "scope": str|None} synonym entries.
-    :returns: A string suitable for BM25 indexing.
+    Arguments:
+        name (str):
+            The primary name of the term.
+        syns (list[SynonymEntry]):
+            List of {"text": str, "scope": str|None} synonym entries.
+
+    Returns:
+        A string suitable for BM25 indexing.
     """
     parts = []
 
@@ -101,20 +116,28 @@ def search(
     logger: logging.Logger | None = None,
     verbose: bool = False,
 ) -> pl.DataFrame:
-    """
-    Given a query string, return the top k hits from the ontology search index.
+    """Given a query string, return the top k hits from the ontology search index.
 
     The search index is built from the ontology terms' names and synonyms, where
     names are weighted more heavily than synonyms. The search uses the BM25+ algorithm
     to rank the results.
 
-    :param query: the query string
-    :param db: path to the DuckDB database file, or None to use the default location
-    :param k: the number of top hits to return
-    :param type: if given, restrict results to this type (e.g. "celltype", "disease", or "tissue")
-    :param ontology: if given, restrict results to this ontology (e.g. "CL", "UBERON", or "MONDO")
-    :param verbose: if True, print debug information
-    :return: a polars DataFrame with columns: term_id, ontology, name, type, synonyms, score
+    Arguments:
+        query (str):
+            The query string.
+        db (Path | None):
+            Path to the DuckDB database file, or None to use the default location.
+        k (int):
+            The number of top hits to return.
+        type (str | None):
+            If given, restrict results to this type (e.g. "celltype", "disease", or "tissue").
+        ontology (str | None):
+            If given, restrict results to this ontology (e.g. "CL", "UBERON", or "MONDO").
+        verbose (bool):
+            If True, print debug information.
+
+    Returns:
+        A `polars.DataFrame` object with columns: term_id, ontology, name, type, synonyms, score.
     """
 
     if logger is None:

metahq_core/util/io.py

@@ -1,17 +1,36 @@
+"""
+Input/output functions.
+
+Author: Parker Hicks
+Date: 2025-04
+
+Last updated: 2025-11-28 by Parker Hicks
+"""
+
 import json
 import re
-import subprocess
 import sys
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 import yaml
 from bson import BSON
 
-from metahq_core.util.alltypes import FilePath, StringArray
+from metahq_core.util.alltypes import StringArray
 
 
-def checkdir(path: FilePath, is_file: bool = False):
+def checkdir(path: str | Path, is_file: bool = False) -> Path:
+    """Check if directory exists. If not, creates it.
+
+    Arguments:
+        path (str | Path):
+            A path to a directory or file.
+        is_file (bool):
+            If `True` will check the parent of the file path.
+
+    Returns:
+        A `pathlib.Path` object of `path`.
+    """
     if isinstance(path, str):
         path = Path(path)
     if is_file:
@@ -23,24 +42,48 @@ def checkdir(path: FilePath, is_file: bool = False):
     return path
 
 
-def load_bson(file: FilePath, **kwargs) -> dict[str, Any]:
-    """Load dictionary from compressed bson."""
+def load_bson(file: str | Path, **kwargs) -> dict[str, Any]:
+    """Load dictionary from compressed bson.
+
+    Arguments:
+        file (str | Path):
+            Path to file.bson to load.
+    """
     with open(file, "rb") as bf:
         return BSON(bf.read()).decode(**kwargs)
 
 
-def load_json(file: FilePath, encoding: str = "utf-8") -> dict[str, Any]:
+def load_json(file: str | Path, encoding: str = "utf-8") -> dict[str, Any]:
+    """Load dictionary from JSON.
+
+    Arguments:
+        file (str | Path):
+            Path to file.json to load.
+    """
     with open(file, "r", encoding=encoding) as jf:
         return json.load(jf)
 
 
 def load_txt(
-    file: FilePath,
+    file: str | Path,
     cols: int = 1,
     delimiter: str = ",",
     encoding: str = "utf-8",
 ) -> list[str]:
-    """Loads a txt file."""
+    """Loads a txt file.
+
+    Arguments:
+        file (str | Path):
+            Path to file.txt to load.
+        cols (int):
+            The number of columns in `file`.
+        delimiter (str | None):
+            Character to separate entries if the `cols>1`.
+        encoding (str):
+            Text encoding format.
+    Returns:
+        An list of strings.
+    """
     out = []
     with open(file, "r", encoding=encoding) as f:
         for line in f.readlines():
@@ -54,21 +97,19 @@ def load_txt(
     return out
 
 
-def load_txt_sections(file: FilePath, delimiter: str, encoding="utf-8") -> list[str]:
-    """
-    Generator to load a .txt file in sections.
+def load_txt_sections(file: str | Path, delimiter: str, encoding="utf-8") -> list[str]:
+    """Load a .txt file in sections.
 
-    Args
-    ----
-    file: FilePath
-        Path to .txt file to load in sections.
+    Arguments:
+        file (str | Path):
+            Path to .txt file to load in sections.
+        delimiter (str):
+            Pattern to split entries in the .txt file.
+        encoding (str):
+            Text encoding format.
 
-    delimter: rstring
-        Pattern to split entries in the .txt file.
-
-    Returns
-    ------
-    Sections of the .txt file separated by the specified delimiter.
+    Returns:
+        Sections of the .txt file separated by the specified delimiter.
 
     """
     with open(file, "r", encoding=encoding) as f:
@@ -77,8 +118,15 @@ def load_txt_sections(file: FilePath, delimiter: str, encoding="utf-8") -> list[
     return re.split(delimiter, text.strip())
 
 
-def load_yaml(file: FilePath, encoding: str = "utf-8") -> dict[str, Any]:
-    """Load a yaml dictionary."""
+def load_yaml(file: str | Path, encoding: str = "utf-8") -> dict[str, Any]:
+    """Load a yaml dictionary.
+
+    Arguments:
+        file (str | Path):
+            Path to .yaml file to load.
+        encoding (str):
+            Text encoding format.
+    """
     with open(file, "r", encoding=encoding) as stream:
         try:
             return yaml.safe_load(stream)
@@ -86,42 +134,57 @@ def load_yaml(file: FilePath, encoding: str = "utf-8") -> dict[str, Any]:
             sys.exit(str(e))
 
 
-def save_bson(data: dict, file: FilePath, **kwargs):
-    """Save dictionary to compressed bson."""
+def save_bson(data: dict, file: str | Path, **kwargs):
+    """Save dictionary to compressed bson.
+
+    Arguments:
+        data (dict):
+            Dictionary to compress and save.
+        file (str | Path):
+            Path to file.txt to save `data`.
+    """
     with open(file, "wb") as bf:
         bf.write(BSON.encode(data, **kwargs))
 
 
-def save_json(data: dict, file: FilePath, encoding: str = "utf-8"):
+def save_json(data: dict, file: str | Path, encoding: str = "utf-8"):
+    """Saves a dictionary to file in JSON format.
+
+    Arguments:
+        data (dict):
+            Dictionary to save.
+        file (str | Path):
+            Path to file.txt to save `data`.
+        encoding (str):
+            Text encoding format.
+    """
     with open(file, "w", encoding=encoding) as jf:
         json.dump(data, jf, indent=4)
 
 
 def save_txt(
     data: StringArray | list[str],
-    file: FilePath,
-    delimiter: Optional[str] = None,
-    encoding="utf-8",
+    file: str | Path,
+    delimiter: str | None = None,
+    encoding: str = "utf-8",
 ):
+    """Save an array or list to a `.txt` file.
+
+    Arguments:
+        data (StringArray | list[str]):
+            An array or list of string entries.
+        file (str | Path):
+            Path to file.txt to save `data`.
+        delimiter (str | None):
+            Allows for multidimensional arrays to be saves as
+                single dimension arrays by concatenating each
+                element in each row by the passed delimiter.
+        encoding (str):
+            Text encoding format.
+    """
     if delimiter:
         data = [delimiter.join(entry) for entry in data]
 
     with open(file, "w", encoding=encoding) as f:
         for entry in data:
             f.write(f"{entry}\n")
-
-
-def run_subprocess(command: str) -> subprocess.CompletedProcess[str] | int:
-    try:
-        result = subprocess.run(
-            ["bash", "-c", command],
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            check=True,
-            text=True,
-        )
-        return result
-
-    except subprocess.CalledProcessError as e:
-        sys.stderr.write(f"{e}\n")
-        return 1

metahq_core/util/supported.py

@@ -7,7 +7,7 @@ Functions beginning with an underscore are intended to be called through the
 Author: Parker Hicks
 Date: 2025-04-15
 
-Last updated: 2025-11-24 by Parker Hicks
+Last updated: 2026-02-02 by Parker Hicks
 """
 
 from pathlib import Path
@@ -122,7 +122,7 @@ def _age_groups() -> list[str]:
         "adolescent",
         "adult",
         "older_adult",
-        "eldery_adult",
+        "elderly_adult",
     ]
 
 
@@ -141,8 +141,6 @@ def species_map() -> dict[str, str]:
     return {
         "human": "homo sapiens",
         "mouse": "mus musculus",
-        "worm": "caenorhabditis elegans",
-        "fly": "drosophila melanogaster",
         "zebrafish": "danio rerio",
         "rat": "rattus norvegicus",
     }
@@ -161,7 +159,13 @@ def get_annotations(level: Literal["sample", "series"]) -> Path:
 
 def get_config():
     """Loads the MetaHQ config file."""
-    return load_yaml(get_config_file())
+    config = load_yaml(get_config_file())
+    if config is None:
+        raise RuntimeError(
+            "The MetaHQ configuration is contaminated. Run `metahq setup`."
+        )
+
+    return config
 
 
 def get_config_file():
@@ -326,6 +330,13 @@ def ecodes(query: list[str] | str) -> list[str]:
     return query
 
 
+def levels(query: str) -> str:
+    """Check if queried level is supported."""
+    if query in supported("levels"):
+        return query
+    raise ValueError(f"Expected query in {supported("levels")}, got {query}.")
+
+
 def metadata_fields(level: str) -> list[str]:
     """Returns supported metadata fields for a specified level."""
     if level == "sample":

{metahq_core-0.1.1.dist-info → metahq_core-1.0.0rc1.dist-info}/METADATA

@@ -1,17 +1,16 @@
 Metadata-Version: 2.4
 Name: metahq-core
-Version: 0.1.1
+Version: 1.0.0rc1
 Summary: Core API for the meta-hq CLI.
 Author-email: Parker Hicks <parker.hicks@cuanschutz.edu>, Faisal Alquaddoomi <faisal.alquaddoomi@cuanschutz.edu>
-Keywords: CLI,Data Curation,Database,Public Biomedical Data
+License-File: LICENSE
+Keywords: Data Curation,Database,Public Biomedical Data
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Requires-Dist: duckdb>=1.4.0
 Requires-Dist: networkx>=3.0
 Requires-Dist: numpy>=2.3.0
@@ -21,14 +20,39 @@ Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pymongo>=4.13.0
 Requires-Dist: pyyaml>=5.1
 Requires-Dist: rank-bm25>=0.2.2
+Requires-Dist: rich>=13.0.0
 Provides-Extra: dev
 Requires-Dist: black; extra == 'dev'
 Requires-Dist: flake8; extra == 'dev'
 Requires-Dist: isort; extra == 'dev'
+Requires-Dist: mkdocs-click; extra == 'dev'
+Requires-Dist: mkdocs-material; extra == 'dev'
+Requires-Dist: mkdocs>=1.6.1; extra == 'dev'
+Requires-Dist: mkdocstrings[python]; extra == 'dev'
 Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pymdown-extensions; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: vulture; extra == 'dev'
 Provides-Extra: test
 Requires-Dist: pytest-benchmark; extra == 'test'
 Requires-Dist: pytest-cov; extra == 'test'
 Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# metahq-core
+
+![Core Tests](https://github.com/krishnanlab/meta-hq/workflows/Core%20Tests/badge.svg)
+![Python](https://img.shields.io/badge/python-3.12+-blue.svg)
+![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)
+![pypi](https://img.shields.io/pypi/v/metahq-core.svg)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+
+Backend package for `metahq-cli` also available on PyPI. Currently this package
+is solely intended to be used through the MetaHQ CLI.
+
+## Install
+
+```bash
+pip install metahq-core
+```

metahq_core-1.0.0rc1.dist-info/RECORD

@@ -0,0 +1,30 @@
+metahq_core/README.md,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+metahq_core/__init__.py,sha256=co7RISTHQOXWWL_YBSfz24445wRZprPGwQxVxn-FWKk,27
+metahq_core/logger.py,sha256=Nq5VjjzrDniL2mZaydniKgElgIWdQOp-k-8DvXCpubU,1165
+metahq_core/query.py,sha256=RlPCUaExFrowfBuwJ8K9SAotTo_ko1FeJr01sskGbq4,22373
+metahq_core/relations_loader.py,sha256=WQMJs4bN9Uy2E8qqrGlDtJMW65A1wt0s4azLLOE0Mew,4758
+metahq_core/search.py,sha256=g0LHprB2Z-8-kmLaOgZ4VUN4RRZNUY_d8RP7Cqzl0c0,10038
+metahq_core/curations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+metahq_core/curations/_multiprocess_propagator.py,sha256=KUiTgcOSLJv0VskzEk2kOpSFHZsUCyupdpOCVdN8vwM,3510
+metahq_core/curations/annotation_converter.py,sha256=lnDjnGOMXspUgUS7YA13G2BZw-mTApkcQU_6H5C1Nt8,8873
+metahq_core/curations/annotations.py,sha256=WXZMTYuNnDXf8K84yCzOxCJiPm59WKyUoIcCvC9VBPY,26559
+metahq_core/curations/base.py,sha256=3Q3gd9G7K4J9rewg7Cn9rAfml1N2Xgor-V2C3OHWeuI,1829
+metahq_core/curations/index.py,sha256=Chy5Y5z8A2ob-cl0JenR1hWunRRikOpc1BdvrORSbtE,5020
+metahq_core/curations/labels.py,sha256=BVnxd9qeRvS7Ji5OR6fTCcneLYJI4PwgVNwZ5jFIVgs,17205
+metahq_core/curations/propagator.py,sha256=o4MDmZ4ziJ3yZv0yDdAHLcvNtLLA9DKK-TdzGMEquT8,9639
+metahq_core/export/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+metahq_core/export/annotations.py,sha256=kut8HaNBp0Sq1T5SQ7X8KywXfGDXSRU2dLO9Dl6He_Y,14728
+metahq_core/export/base.py,sha256=j7cKc-ru0ggAXEmGFYiaxBn_OROahQ9HPiR1tK-VX94,1394
+metahq_core/export/labels.py,sha256=K9BFz8e-kJtDQOr9RwlF2ebsjWuxWbLUsoojourKeFw,14816
+metahq_core/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+metahq_core/util/alltypes.py,sha256=zYrBKvtkAhR7lmqDlGp7BOh2bUNI-toQfd7o7isDCxw,721
+metahq_core/util/checkers.py,sha256=_7Aw2bO1PNg-9TPYOwKwvTqFtmb5vMyYU-omfUID_DE,508
+metahq_core/util/exceptions.py,sha256=FlYUN8g4lNB3OSwQ20dfnSDmgX8NKZV5Yx7xERurrWc,115
+metahq_core/util/helpers.py,sha256=sak1A7gp2qvnbhCBYHNQ5IUxIZeljgyRSu5U7C8a7bU,949
+metahq_core/util/io.py,sha256=oouWuSZhECiXdZN7K9cXU0q4O8RqsEMsiVOpTrsX2gg,4730
+metahq_core/util/progress.py,sha256=NF158KVFO9pO3vrsl7OrPAhYtd-cXaXRavL0iOV5XeM,2128
+metahq_core/util/supported.py,sha256=UJ8S7esdOTFW5oq9kIHQ1N5GPanXIgntVvxMrgiCjjM,11287
+metahq_core-1.0.0rc1.dist-info/METADATA,sha256=QTTHZqHXg4Uu7QLEUmow5_Cp_rkcruJQ4N5TbwxUIn8,2183
+metahq_core-1.0.0rc1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+metahq_core-1.0.0rc1.dist-info/licenses/LICENSE,sha256=1KNh4-XEVT4pk2tvDi-deIXms0suss2eiYLBKBiQDGo,1499
+metahq_core-1.0.0rc1.dist-info/RECORD,,

{metahq_core-0.1.1.dist-info → metahq_core-1.0.0rc1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

metahq_core-1.0.0rc1.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Krishnan Lab
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.