Models and data¶

PEAgent Tool ships code only. Model weights and cell-group metadata are runtime assets you obtain once and reuse.

Each species needs exactly two files:

File	What it is	Size
`models/<species>/model.h5`	Trained model weights	31–71 MB
`metadata/<species>_group_metadata.csv`	Which model output cells belong to which `tissue_celltype` group	0.3–1.5 MB

Where the package looks¶

peagent_tool resolves each asset in this order and stops at the first hit:

an explicit model_path= / metadata_path= argument;
$PEAGENT_ASSET_ROOT, a directory laid out as below;
the local cache, $PEAGENT_CACHE_DIR (default ~/.cache/peagent);
a download from the Hugging Face Hub into that cache.

<root>/
├── models/
│   ├── soybean/model.h5
│   ├── maize/model.h5
│   └── rice/model.h5
└── metadata/
    ├── soybean_group_metadata.csv
    ├── maize_group_metadata.csv
    └── rice_group_metadata.csv

Check what will be used, without loading anything:

peagent-tool assets --species maize

from peagent_tool import describe_assets

describe_assets("maize")

Downloading from Hugging Face¶

Weights are released after peer review

The trained model weights are being held until the accompanying manuscript completes peer review, so the Hugging Face repository is not live yet. This page will be updated with the repository id and a direct download the moment it is.

Until then, point the package at a local copy with $PEAGENT_ASSET_ROOT or explicit model_path= / metadata_path= arguments — see Using files you already have. Everything else in the package and in the tutorials works unchanged; only the download step is unavailable.

Once the repository is published, the download path is:

pip install "peagent-tool[hub]"

The first call that needs a model downloads it into ~/.cache/peagent and reuses it afterwards:

from peagent_tool import fetch_species_assets

fetch_species_assets("maize")

The repository id is configurable, so you can point the package at a mirror or at your own copy without touching code:

export PEAGENT_HF_REPO=YAOJ-bioin/peagent      # default
export PEAGENT_HF_REVISION=main                # branch, tag or commit
export PEAGENT_CACHE_DIR=/data/peagent-cache   # where downloads land

Using files you already have¶

If the weights came from somewhere else — a collaborator, a Zenodo archive, your own fine-tuning run — either lay them out under one root:

export PEAGENT_ASSET_ROOT=/data/peagent
# /data/peagent/models/maize/model.h5
# /data/peagent/metadata/maize_group_metadata.csv

or pass the paths explicitly, which overrides everything:

from peagent_tool import predict_celltypes

predict_celltypes(
    sequence,
    species="maize",
    model_path="/data/my_maize_model.h5",
    metadata_path="/data/my_group_metadata.csv",
)

The cell-group metadata file¶

This CSV is what turns 50,639 per-cell outputs into 94 interpretable cell-type scores. One row per group:

Column	Meaning
`tissue_celltype`	Group name, and the exact string you pass as `target`
`tissue`, `celltype`	The two components of that name
`n_cells`	Number of nuclei in the group
`group_idx`	Row order
`cell_indices`	JSON list of model output indices belonging to the group

Groups below the minimum-cell threshold are not included, which is why the group count is smaller than the number of annotated cell types in the atlas. List them with:

peagent-tool list-celltypes --species maize

Custom cell groupings

Nothing forces you to use the published grouping. Write your own CSV with the same columns — merging cell types, splitting by replicate, defining an arbitrary set of cells — and pass it as metadata_path. The model is untouched; only the aggregation changes.

Genome FASTA¶

Only variant scoring from coordinates needs a genome, and it must be the assembly the model was trained on:

Species	Assembly
Soybean	Wm82.a4.v1
Maize	B73 NAM-5.0
Rice	Nipponbare MSU7 (osa1 r7)

Keep the .fai index (and .gzi for bgzipped FASTA) next to the file so pysam can seek into it.