Refine

README.md

@@ -1,8 +1,10 @@
-# ariadnePy
+# ariadnePy: a Python interface to the ariadne database network <img src="https://raw.githubusercontent.com/Minotau-R/ariadne/devel/inst/assets/ariadne_logo.png" align="right" width="120" />
 
-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--- <N vertices> <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"})
+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")
 ```
 
 ---
 
-<!-- ## Supported resources
+## Supported resources
 
 | Resource | Description |
 |---|---|
@@ -61,28 +81,30 @@ g = ariadnepy.ariadne(versions={"GO": "2026-01-23", "KEGG": "latest"})
 | Rhea | Rhea biochemical reactions |
 | WoL | Web of Life phylogenetic tree |
 | TIGRFAMs | TIGRFAM protein families |
-| GM | Gut Metabolome modules |
+| GM | Gut Metabolic Modules |
 | BugSigDB | Bug Signatures Database |
 | ChocoPhlAn | MetaPhlAn gene families |
 | MSigDB | Molecular Signatures Database |
 
---- -->
+Run `ariadnepy.list_resource_versions()` for the exact versions available at any time.
+
+---
 
 ## 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
+│       ├── __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.

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",