xenosite.forest

Python implementation of Metabolic Forest: enumerate explicit metabolite structures from reaction rules, and search pathways that connect a reactant to a putative product.

Site-of-metabolism prediction models (epoxidation, quinonation, Phase I, reactivity, and others) are on the web at xenosite.org. This package is the structure-enumeration engine, not those neural-network models.

If you use this software, please cite the Metabolic Forest paper (DOI and BibTeX below).

Install

uv add xenosite-forest

or

pip install xenosite-forest

The default install is the Rust chematic door (no RDKit). For the RDKit reference engine and the frozen 0.6.x archive:

uv add "xenosite-forest[rdkit]"

Optional NetworkX helpers for building a metabolite graph:

uv add "xenosite-forest[network]"

Optional xenosite-predict (site-of-metabolism models; Python ≥3.11). Not installed in this repo’s CI:

uv add "xenosite-forest[predict]"

Requires Python 3.11–3.14. RDKit 2022.03+ only with the [rdkit] extra.

A WASM-clean Rust crate (chematic + canonaut) lives in crates/xenosite-forest. See docs/forest/RUST.md and docs/forest/MIGRATING_0.8.md.

Quick start

from xenosite.forest import find_path, PhaseOne, Epoxidation

hits, counters = find_path("CC", "CCO", max_paths=1)
print(hits[0]["steps"], counters["billed"])

RDKit reference engine (requires [rdkit]):

from rdkit import Chem
from xenosite.forest.native import bfs, rules, PhaseOneRS

smiles, steps, mols = next(bfs(["CCO", "CC=O"], ruleset="PhaseOneRS"))
print(smiles, steps)

for products, info in rules.Hydroxylation().metabolize(Chem.MolFromSmiles("CCC")):
    print(info["site"], [p.xf.csmi for p in products])

A longer walkthrough is in examples/tutorial.ipynb. API notes are in docs/usage.md. Rulesets and their papers are in docs/rulesets.md.

Command line

Requires the [rdkit] extra (temporary native bridge until a Rust CLI ships):

xenosite-forest CCO CC=O --ruleset PhaseOneRS --depth 1

Useful flags: --all-paths, --depth N, --phase1 (Phase I site strings), --max N, --ruleset NAME.

Rulesets and papers

Pass these names to bfs(..., ruleset=...) or load_ruleset(...). Full rule lists, Rainbow colors/hex codes, aliases, and BibTeX are in docs/rulesets.md.

Rainbow colorblind-safe hex (Wong / Okabe–Ito, closest to the paper figures): SO Stable Oxygenation red #D55E00, UO Unstable Oxygenation orange #E69F00, DH Dehydrogenation green #009E73, HD Hydrolysis blue #56B4E9, RD Reduction purple #CC79A7.

Related single-rule papers: epoxidation (10.1021/acscentsci.5b00131), N-dealkylation (10.1021/acs.chemrestox.7b00191), UGT glucuronidation (10.1093/bioinformatics/btw350), glutathione reactivity (10.1021/acs.chemrestox.5b00017).

Documentation

• Rulesets and papers — every built-in ruleset, Rainbow colors, and publication BibTeX
• Usage — public API and pathway search
• Migrating to 0.7.0 — metabolize yield shape and other breaking changes
• Migrating to 0.8.0 — rust / native / legacy layout, optional RDKit
• Legacy freeze — frozen 0.6.x archive notes
• xenosite-predict notes — RDKit 2026 valence caches and DNA/CN conjugation vs GSH (downstream adapters)
• Path-search performance — archive BFS/DFS vs live find_path head-to-head
• Heuristics / divergences / dropped — design notes (HEURISTICS, DIVERGENCES, DROPPED, PAIR_ORBITS)
• Tutorial notebook — interactive walkthrough
• xenosite.org — XenoSite models for sites of metabolism and reactivity
• Source repository — code, issues, and releases

Import the package as xenosite.forest (Rust public stub). The RDKit reference engine is xenosite.forest.native; the frozen 0.6.x archive is xenosite.forest.legacy (see docs/forest/LEGACY.md). xenosite is a PEP 420 namespace, so other xenosite.* packages can be installed alongside this one.

Citation

Please cite Metabolic Forest if you use this package:

Hughes, T. B.; Dang, N. L.; Kumar, A.; Flynn, N. R.; Swamidass, S. J. Metabolic Forest: Predicting the Diverse Structures of Drug Metabolites. J. Chem. Inf. Model. 2020, 60 (10), 4702–4716. DOI: 10.1021/acs.jcim.0c00360

BibTeX (copy and paste):

@article{Hughes2020MetabolicForest,
  title = {Metabolic Forest: Predicting the Diverse Structures of Drug Metabolites},
  author = {Hughes, Tyler B. and Dang, Na Le and Kumar, Ayush and Flynn, Noah R. and Swamidass, S. Joshua},
  journal = {Journal of Chemical Information and Modeling},
  volume = {60},
  number = {10},
  pages = {4702--4716},
  year = {2020},
  doi = {10.1021/acs.jcim.0c00360},
  url = {https://doi.org/10.1021/acs.jcim.0c00360},
  publisher = {American Chemical Society}
}

A machine-readable citation is also in CITATION.cff.

Development

git clone https://github.com/swamidasslab/xenosite-forest.git
cd xenosite-forest
uv sync --extra network --group dev
uv run pytest -n auto
uv run pytest --cov=xenosite.forest

Versioning comes from git tags via hatch-vcs (setuptools-scm). Tag a release as vX.Y.Z (for example v0.1.0). On that commit the version is X.Y.Z. On later untagged commits it becomes the next patch with a dev suffix and short commit, for example 0.1.1.dev3+gabc1234. Read it at runtime as xenosite.forest.__version__. User-facing notes go in changelog.d/; the tag workflow compiles them into CHANGELOG.md. See docs/release.md.

Pushing a v* tag runs .github/workflows/release.yml: tests must pass and the resolved version must be a clean X.Y.Z before a GitHub Release and PyPI upload. A red tag workflow means do not treat that tag as released. To block creating tags unless checks pass, add a GitHub Ruleset on refs/tags/v* that requires the release / test status checks.

License

MIT. See LICENSE.