ariadnepy 0.1.0__tar.gz

ariadnepy-0.1.0/.github/workflows/build.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"  # triggers on version tags like v0.1.0, v1.2.3
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tool
+        run: pip install build
+
+      - name: Build wheel and source distribution
+        run: python -m build
+
+      - name: Upload distributions as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publisher (OIDC) — no API token needed
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ariadnepy-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package and dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/
+
+      - name: Run tests
+        run: pytest --tb=short -q

ariadnepy-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checkers
+.mypy_cache/
+.ruff_cache/
+
+# ariadne cache
+.ariadne_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

ariadnepy-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: ariadnepy
+Version: 0.1.0
+Summary: Python interface to the ariadne multi-omic knowledge graph
+Project-URL: Homepage, https://github.com/Minotau-R/ariadne
+Project-URL: Bug Tracker, https://github.com/Minotau-R/ariadne/issues
+Author-email: Aditi <abhiyan@analyticsandsociety.com>
+License: Artistic-2.0
+Keywords: bioinformatics,graph,knowledge-graph,microbiome,multi-omics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Artistic License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: igraph>=0.11
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: pandas>=2.0
+Requires-Dist: platformdirs>=3.0
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: pyreadr>=0.5
+Requires-Dist: requests>=2.28
+Requires-Dist: scipy>=1.10
+Provides-Extra: anndata
+Requires-Dist: anndata>=0.10; extra == 'anndata'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pandas-stubs; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ariadnePy
+
+Python interface to the [ariadne](https://github.com/Minotau-R/ariadne) multi-omic knowledge graph.
+
+ariadnePy brings the biological database integration and graph-theory tools of the R package **ariadne** to Python users. It downloads biological resources (Gene Ontology, KEGG, UniProt, BugSigDB, ChocoPhlAn, and more) from [Zenodo](https://zenodo.org) and assembles them into a single [NetworkX](https://networkx.org) `MultiDiGraph` that can be queried, filtered, and visualised directly in Python.
+
+---
+
+## Installation
+
+```bash
+pip install ariadnepy
+```
+
+To also read RDS files (required for MSigDB):
+
+```bash
+pip install "ariadnepy[rds]"
+```
+
+For development:
+
+```bash
+git clone https://github.com/Minotau-R/ariadnePy
+cd ariadnePy
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick start
+
+```python
+import ariadnepy
+
+# Build the knowledge graph using default resource versions
+# (downloads GML files from Zenodo on first run; cached locally afterwards)
+g = ariadnepy.ariadne()
+
+print(g)
+# MultiDiGraph with N nodes and M edges
+
+# List all available resource versions
+df = ariadnepy.list_resource_versions()
+print(df.head())
+
+# Select specific versions
+g = ariadnepy.ariadne(versions={"GO": "2026-01-23", "KEGG": "latest"})
+```
+
+---
+
+<!-- ## Supported resources
+
+| Resource | Description |
+|---|---|
+| GO | Gene Ontology |
+| KEGG | KEGG Pathways & Modules |
+| UniProt | UniProt protein database |
+| OTT | Open Tree of Life Taxonomy |
+| Rhea | Rhea biochemical reactions |
+| WoL | Web of Life phylogenetic tree |
+| TIGRFAMs | TIGRFAM protein families |
+| GM | Gut Metabolome modules |
+| BugSigDB | Bug Signatures Database |
+| ChocoPhlAn | MetaPhlAn gene families |
+| MSigDB | Molecular Signatures Database |
+
+--- -->
+
+## Project structure
+
+```
+ariadnePy/
+├── src/
+│   └── ariadnepy/
+│       ├── __init__.py     # public API
+│       ├── _core.py        # ariadne() graph builder
+│       ├── _cache.py       # resource downloading & caching
+│       ├── _utils.py       # utility functions
+│       └── _custom.py      # custom resource support
+├── tests/
+│   ├── test_core.py
+│   ├── test_cache.py
+│   └── test_utils.py
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Running tests
+
+```bash
+pytest
+```
+
+---
+
+## License
+

ariadnepy-0.1.0/README.md

@@ -0,0 +1,101 @@
+# ariadnePy
+
+Python interface to the [ariadne](https://github.com/Minotau-R/ariadne) multi-omic knowledge graph.
+
+ariadnePy brings the biological database integration and graph-theory tools of the R package **ariadne** to Python users. It downloads biological resources (Gene Ontology, KEGG, UniProt, BugSigDB, ChocoPhlAn, and more) from [Zenodo](https://zenodo.org) and assembles them into a single [NetworkX](https://networkx.org) `MultiDiGraph` that can be queried, filtered, and visualised directly in Python.
+
+---
+
+## Installation
+
+```bash
+pip install ariadnepy
+```
+
+To also read RDS files (required for MSigDB):
+
+```bash
+pip install "ariadnepy[rds]"
+```
+
+For development:
+
+```bash
+git clone https://github.com/Minotau-R/ariadnePy
+cd ariadnePy
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick start
+
+```python
+import ariadnepy
+
+# Build the knowledge graph using default resource versions
+# (downloads GML files from Zenodo on first run; cached locally afterwards)
+g = ariadnepy.ariadne()
+
+print(g)
+# MultiDiGraph with N nodes and M edges
+
+# List all available resource versions
+df = ariadnepy.list_resource_versions()
+print(df.head())
+
+# Select specific versions
+g = ariadnepy.ariadne(versions={"GO": "2026-01-23", "KEGG": "latest"})
+```
+
+---
+
+<!-- ## Supported resources
+
+| Resource | Description |
+|---|---|
+| GO | Gene Ontology |
+| KEGG | KEGG Pathways & Modules |
+| UniProt | UniProt protein database |
+| OTT | Open Tree of Life Taxonomy |
+| Rhea | Rhea biochemical reactions |
+| WoL | Web of Life phylogenetic tree |
+| TIGRFAMs | TIGRFAM protein families |
+| GM | Gut Metabolome modules |
+| BugSigDB | Bug Signatures Database |
+| ChocoPhlAn | MetaPhlAn gene families |
+| MSigDB | Molecular Signatures Database |
+
+--- -->
+
+## Project structure
+
+```
+ariadnePy/
+├── src/
+│   └── ariadnepy/
+│       ├── __init__.py     # public API
+│       ├── _core.py        # ariadne() graph builder
+│       ├── _cache.py       # resource downloading & caching
+│       ├── _utils.py       # utility functions
+│       └── _custom.py      # custom resource support
+├── tests/
+│   ├── test_core.py
+│   ├── test_cache.py
+│   └── test_utils.py
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Running tests
+
+```bash
+pytest
+```
+
+---
+
+## License
+

ariadnepy-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ariadnepy"
+version = "0.1.0"
+description = "Python interface to the ariadne multi-omic knowledge graph"
+readme = "README.md"
+license = { text = "Artistic-2.0" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Aditi", email = "abhiyan@analyticsandsociety.com" },
+]
+keywords = ["bioinformatics", "multi-omics", "graph", "knowledge-graph", "microbiome"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Artistic License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "igraph>=0.11",
+    "pandas>=2.0",
+    "requests>=2.28",
+    "platformdirs>=3.0",
+    "pyarrow>=14.0",
+    "pyreadr>=0.5",
+    "scipy>=1.10",
+    "matplotlib>=3.7",
+]
+
+[project.optional-dependencies]
+anndata = ["anndata>=0.10"]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "responses>=0.25",
+    "ruff>=0.4",
+    "mypy>=1.10",
+    "pandas-stubs",
+]
+
+[project.urls]
+Homepage = "https://github.com/Minotau-R/ariadne"
+"Bug Tracker" = "https://github.com/Minotau-R/ariadne/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ariadnepy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short -q"
+
+[tool.ruff]
+src = ["src"]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "PT"]
+ignore = ["B008"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true

ariadnepy-0.1.0/src/ariadnepy/__init__.py

@@ -0,0 +1,49 @@
+"""ariadnepy — Python extension of the ariadne multi-omic graph package."""
+
+from ariadnepy._version import __version__
+from ariadnepy.anndata._humann import process_gene_families
+from ariadnepy.anndata._modules import add_modules, get_modules
+from ariadnepy.core._graph import ariadne
+from ariadnepy.core._versions import list_resource_versions
+from ariadnepy.exceptions import (
+    AriadneCacheError,
+    AriadneDownloadError,
+    AriadneError,
+    AriadneParseError,
+    AriadnePathError,
+    AriadneVersionError,
+)
+from ariadnepy.graph._names import link_names
+from ariadnepy.graph._weave import draw_path, search_path, weave_complex, weave_path
+from ariadnepy.plot._custom import add_resource
+from ariadnepy.plot._draw import plot_path
+from ariadnepy.resources._data import load_butyrate
+
+__all__ = [
+    "__version__",
+    # exceptions
+    "AriadneError",
+    "AriadneDownloadError",
+    "AriadneVersionError",
+    "AriadneParseError",
+    "AriadnePathError",
+    "AriadneCacheError",
+    # core
+    "ariadne",
+    "list_resource_versions",
+    # graph traversal
+    "weave_path",
+    "weave_complex",
+    "draw_path",
+    "search_path",
+    "link_names",
+    # plot
+    "plot_path",
+    "add_resource",
+    # data
+    "load_butyrate",
+    # anndata integration
+    "add_modules",
+    "get_modules",
+    "process_gene_families",
+]

ariadnepy-0.1.0/src/ariadnepy/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ariadnepy-0.1.0/src/ariadnepy/anndata/__init__.py

@@ -0,0 +1,6 @@
+"""AnnData integration — Python equivalent of R's SummarizedExperiment helpers."""
+
+from ariadnepy.anndata._humann import process_gene_families
+from ariadnepy.anndata._modules import add_modules, get_modules
+
+__all__ = ["add_modules", "get_modules", "process_gene_families"]

ariadnepy-0.1.0/src/ariadnepy/anndata/_humann.py

@@ -0,0 +1,102 @@
+"""process_gene_families — mirrors R's processGeneFamilies in ariadne.
+
+Prepares an AnnData object containing HUMAnN gene families by parsing
+the feature names into uniref90, taxname, genus, and species columns
+and adding them to adata.var.
+
+R equivalent:
+    processGeneFamilies(genes)
+
+HUMAnN feature name format:
+    UniRef90_XXXXXX|g__Genus.s__species
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+from ariadnepy.exceptions import AriadneError
+
+if TYPE_CHECKING:
+    from anndata import AnnData
+
+
+def _require_anndata() -> None:
+    try:
+        import anndata  # noqa: F401
+    except ImportError:
+        raise AriadneError(
+            "'anndata' is required for process_gene_families. "
+            "Install with: pip install anndata"
+        ) from None
+
+
+def process_gene_families(adata: AnnData) -> AnnData:
+    """Parse HUMAnN gene family feature names and add metadata to adata.var.
+
+    Filters to features that contain a ``|`` separator and do not contain
+    ``"unclassified"``, then splits the name into four columns:
+    ``uniref90``, ``taxname``, ``genus``, and ``species``.
+
+    Equivalent to R's ``processGeneFamilies(genes)``.
+
+    Parameters
+    ----------
+    adata:
+        AnnData object whose ``var_names`` follow the HUMAnN format
+        ``UniRef90_XXXXXX|g__Genus.s__species``.
+
+    Returns
+    -------
+    AnnData
+        Filtered AnnData (unclassified and non-stratified rows removed)
+        with four new columns in ``adata.var``:
+        ``uniref90``, ``taxname``, ``genus``, ``species``.
+
+    Examples
+    --------
+    >>> from ariadnepy import process_gene_families
+    >>> genes = process_gene_families(genes)
+    >>> genes.var.head()
+    """
+    _require_anndata()
+
+    names = pd.Series(adata.var_names, index=adata.var_names)
+
+    # Keep only stratified (contains |) and classified features
+    mask = names.str.contains("|", regex=False) & ~names.str.contains(
+        "unclassified", case=False, regex=False
+    )
+
+    if not mask.any():
+        raise AriadneError(
+            "No valid HUMAnN gene family features found. "
+            "Expected feature names like 'UniRef90_XXXXX|g__Genus.s__species'."
+        )
+
+    adata = adata[:, mask].copy()
+    names = pd.Series(adata.var_names, index=adata.var_names)
+
+    # Split on | to get uniref90 and taxname
+    split_gene = names.str.split("|", n=1, expand=True)
+    split_gene.columns = ["uniref90", "taxname"]
+    split_gene.index = adata.var_names
+
+    # Split taxname on . to get genus and species
+    split_tax = split_gene["taxname"].str.split(".", n=1, expand=True)
+    split_tax.columns = ["genus", "species"]
+    split_tax.index = adata.var_names
+
+    # Append to existing var
+    for col in ["uniref90", "taxname", "genus", "species"]:
+        if col in adata.var.columns:
+            import warnings
+            warnings.warn(f"Column '{col}' in adata.var was replaced.", UserWarning, stacklevel=2)
+
+    adata.var = pd.concat(
+        [adata.var, split_gene[["uniref90", "taxname"]], split_tax],
+        axis=1,
+    )
+
+    return adata