PEAgent Tool

Sequence-to-single-cell chromatin accessibility for plant genomes.

PEAgent Tool is the inference package for the PEAgent models: per-species neural networks that predict, from 1,344 bp of DNA sequence alone, whether a region is accessible in each cell type of a single-cell ATAC atlas — and which bases in that sequence drive the prediction.

📖 Documentation and tutorials

pip install "peagent-tool[all]"

from peagent_tool import predict_celltypes, compute_attribution

# What cell types is this sequence accessible in?
predict_celltypes(sequence, species="maize", top_k=5)

# Which bases make it accessible in one cell type, specifically?
result = compute_attribution(
    sequence, species="maize", target="crownRoot_trichoblast", normalize="tissue"
)

What it does

Predict accessibility	Score any sequence — genomic, edited or synthetic — across every tissue_celltype group of an atlas.
Contribution maps	Per-base attribution by bottleneck in-silico mutagenesis, in the raw and the tissue-normalized convention used by the PEAgent browser.
Variant effects	REF/ALT scoring of biallelic SNVs from a genome FASTA or from sequences you built yourself.
Motif synergy	In-silico marginalization over a spacing × orientation grid, with a paired Wilcoxon test.

The three atlases

Species	Assembly	Nuclei	tissue_celltype groups	Tissues
Soybean (Glycine max)	Wm82.a4.v1	200,732	98	10
Maize (Zea mays)	B73 NAM-5.0	50,639	94	6
Rice (Oryza sativa)	Nipponbare MSU7	104,029	128	9

All models share a convolutional trunk, a 64-dimensional bottleneck embedding common to every cell, and a per-cell output head. Because the bottleneck is shared, a single in-silico mutagenesis pass gives contribution scores for every cell type at once.

Models and data

The package ships code only. Model weights and cell-group metadata are resolved from an explicit path, $PEAGENT_ASSET_ROOT, the local cache (~/.cache/peagent), or a Hugging Face download — in that order. See Models and data.

Model weights are released after peer review. The Hugging Face repository is not live yet; until it is, point the package at a local copy with $PEAGENT_ASSET_ROOT. Nothing else about the package or the tutorials depends on it.

peagent-tool assets --species maize     # where will they be read from?

Command line

peagent-tool list-celltypes    --species maize
peagent-tool predict-celltypes --species maize --fasta seqs.fa --top-k 10
peagent-tool attribution       --species maize --fasta acr.fa \
                               --target crownRoot_trichoblast --normalize tissue \
                               --out-prefix contribution
peagent-tool score-variants    --species maize --variants snvs.tsv --fasta genome.fa.gz

Consistency

The tissue-normalized contribution scores reproduce the attribution tracks served by the PEAgent genome browser to within float32 noise (median Pearson r = 0.999995 across 115 cell-type tracks). See the consistency check.

Development

git clone https://github.com/YAOJ-bioin/peagent_tool.git
cd peagent_tool
pip install -e ".[all,test]"
pytest
ruff check src tests
mkdocs serve

The tutorial notebooks under docs/tutorials/ are executed against the published models and committed with their outputs, so the documentation always shows real results rather than illustrative ones.

Citation

This package accompanies:

Yao J. et al. Sequence-based modeling of plant epigenomes reveals cell-type-specific cis-regulatory grammar. Under review (2026).

The model architecture derives from scBasset (Yuan & Kelley, Nat. Methods 2022); see THIRD_PARTY_NOTICES.md.

License

MIT — see LICENSE.