diff --git a/README.md b/README.md index 56ae328..4347394 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ -# ariadnePy +# ariadnePy: a Python interface to the ariadne database network -Python interface to the [ariadne](https://github.com/Minotau-R/ariadne) multi-omic knowledge graph. +[![issues](https://img.shields.io/github/issues/Minotau-R/ariadnePy)](https://github.com/Minotau-R/ariadnePy/issues) +[![pulls](https://img.shields.io/github/issues-pr/Minotau-R/ariadnePy)](https://github.com/Minotau-R/ariadnePy/pulls) +[![tests](https://github.com/Minotau-R/ariadnePy/actions/workflows/test.yml/badge.svg)](https://github.com/Minotau-R/ariadnePy/actions/workflows/test.yml) -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. +ariadnePy brings the biological database integration and graph-theory tools of the R package [ariadne](https://github.com/Minotau-R/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 [igraph](https://python.igraph.org) `Graph` that can be queried, filtered, and visualised directly in Python. --- @@ -12,10 +14,12 @@ ariadnePy brings the biological database integration and graph-theory tools of t pip install ariadnepy ``` -To also read RDS files (required for MSigDB): +RDS-backed resources (e.g. MSigDB) are supported out of the box — `pyreadr` is installed as a core dependency. + +To also use the AnnData integration helpers (`add_modules`, `get_modules`, `process_gene_families`): ```bash -pip install "ariadnepy[rds]" +pip install "ariadnepy[anndata]" ``` For development: @@ -35,22 +39,38 @@ import ariadnepy # Build the knowledge graph using default resource versions # (downloads GML files from Zenodo on first run; cached locally afterwards) -g = ariadnepy.ariadne() +graph = ariadnepy.ariadne() -print(g) -# MultiDiGraph with N nodes and M edges +print(graph) +# IGRAPH U--- -- # 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"}) +graph = ariadnepy.ariadne(versions={"GO": "2026-01-23", "KEGG": "latest"}) + +# Explore a few candidate paths between two resources +ariadnepy.search_path(graph, "ko ~ ec", k=3) + +# Weave a linkmap along a chosen path +linkmap = ariadnepy.weave_path(graph, "taxname ~ bugsig", init=["s__Bacteroides_fragilis"]) + +# weave_path / weave_complex also accept an existing pathway DataFrame +# (e.g. from draw_path(), or the bundled pathMeta example) instead of the +# full graph, skipping path search entirely and re-running just those steps: +pathmeta = ariadnepy.load_pathmeta() +chebi2gmm = ariadnepy.weave_path(pathmeta, init=[15377, 30616, 4167]) + +# Visualise a path on the graph +fig = ariadnepy.plot_path(graph, "ko ~ ec", k=1) +fig.savefig("path.png") ``` --- - +Run `ariadnepy.list_resource_versions()` for the exact versions available at any time. + +--- ## Project structure @@ -74,15 +96,15 @@ g = ariadnepy.ariadne(versions={"GO": "2026-01-23", "KEGG": "latest"}) 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 +│ ├── __init__.py # public API +│ ├── core/ # ariadne() graph builder, GML download/cache, resource versions +│ ├── graph/ # weave_path, weave_complex, draw_path, search_path, link_names +│ ├── io/ # SPARQL (UniProt/Rhea) and Open Tree of Life query backends +│ ├── plot/ # plot_path, add_resource +│ ├── resources/ # resource file caching/parsing, bundled example datasets +│ ├── anndata/ # AnnData integration (add_modules, get_modules, process_gene_families) +│ └── exceptions.py +├── tests/ # mirrors the src/ package layout ├── pyproject.toml └── README.md ``` @@ -99,3 +121,4 @@ pytest ## License +Artistic License 2.0, matching the [ariadne](https://github.com/Minotau-R/ariadne) R package. diff --git a/src/ariadnepy/__init__.py b/src/ariadnepy/__init__.py index 28f3d92..9a37b60 100644 --- a/src/ariadnepy/__init__.py +++ b/src/ariadnepy/__init__.py @@ -17,7 +17,7 @@ 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 +from ariadnepy.resources._data import load_butyrate, load_pathmeta __all__ = [ "__version__", @@ -42,6 +42,7 @@ "add_resource", # data "load_butyrate", + "load_pathmeta", # anndata integration "add_modules", "get_modules",