Python API

Everything below is importable from the top-level package: from peagent_tool import ....

Prediction

predict_celltypes(sequences, species, ...)

One-shot prediction. Returns a long, ranked table: one row per sequence × tissue_celltype.

Argument	Default	Meaning
sequences	—	A string, FASTA text, list of strings, or {id: sequence} mapping
species	—	"soybean", "maize" or "rice" (Latin names and common aliases accepted)
mode	"exact"	"exact" predicts all cells then averages probabilities per group; "fast" averages the group's final-layer parameters first
top_k	None	Keep only the top k groups per sequence
batch_size	32	Sequences per model batch
model_path, metadata_path, n_cells	None	Override asset resolution

Output columns: sequence_id, rank, prediction, tissue_celltype, tissue, celltype, n_cells, original_length, normalized_length, normalization_action, species, mode, model_path.

load_predictor(species, ...) -> CellTypePredictor

Builds the model once and keeps it. Use it for more than one call.

• .predict(sequences, top_k=None, batch_size=32) — the long table above.
• .predict_wide(sequences, batch_size=32) — one row per sequence, one column per tissue_celltype.
• .valid_celltypes — the group names, in model order.
• .group_metadata — the parsed metadata frame.

list_valid_celltypes(species, ...)

The valid tissue_celltype groups with their tissue, cell type and nucleus count. Reads only the metadata file, so it never triggers a model download.

Contribution scores

compute_attribution(sequences, species, target, normalize, ...) -> AttributionResult

Argument	Default	Meaning
target	"global"	"global", or one exact tissue_celltype
normalize	"none"	"none" raw scores; "tissue" subtracts the mean over all groups of the target's tissue
position_batch_size	64	Sequence positions mutated per model batch

One sequence per call. normalize="tissue" requires a tissue_celltype target — "global" has no tissue.

ContributionScorer(species, ...)

The reusable form, and the only way to get several targets from a single ISM pass.

• .compute(sequences, target, normalize, position_batch_size) — one result.
• .compute_many(sequences, targets, normalize, position_batch_size) — a {target: AttributionResult} mapping computed from one ISM pass.
• .bottleneck_ism(record, position_batch_size) — the raw (L, 4, 64) tensor.
• .target_weights(target) — the bottleneck weight vector for a target.
• .tissues, .celltypes_in_tissue(tissue), .valid_celltypes.

AttributionResult

Attribute	Shape	Meaning
attribution	(1344, 4)	Reference-projected scores, after the chosen normalization
raw_attribution	(1344, 4)	The same before tissue normalization, always present
hypothetical	(1344, 4)	Scores for every possible base — the TF-MoDISco input
profile	(1344,)	Per-position score of the reference base
tissue_reference	tuple	The groups averaged for tissue normalization

Methods: attribution_dataframe(), hypothetical_dataframe(), to_dataframe(position_offset=0), describe().

Plotting

• plot_attribution(result, out_prefix=None, plot_start=None, plot_end=None, position_offset=0, title=None, ax=None) — a logo map. With out_prefix, writes .pdf and .png (600 dpi, Illustrator-compatible fonts) and returns the paths; with ax, draws into an existing axis; otherwise returns the figure.
• plot_attribution_panels(results, ...) — several targets stacked over the same window, share_y=True by default.
• compute_and_plot_attribution(...) — both in one call.

plot_start / plot_end are 1-based positions on the normalized 1,344 bp window; position_offset shifts only the axis labels, for genome coordinates.

Variant effects

score_variants(variants, species, genome_fasta, targets=None, ...)

variants is a DataFrame, a list of VariantRecord, or a path-like table with chrom, pos (1-based), ref, alt and optional variant_id. targets accepts "all", "global", or a list of tissue_celltype names.

Each window is centred on the variant and the FASTA base is checked against the declared REF allele. Output carries ref_probability, alt_probability, delta_probability, ref_logit, alt_logit, delta_logit, abs_delta_logit and the window bookkeeping.

score_ref_alt_sequences(ref_sequences, alt_sequences, species, targets=None, ...)

For alleles that do not come from a genome.

Motif synergy

MotifSynergyTester(species, ...)

• .test_pair(motif_a, motif_b, target, backgrounds, spacings, orientations=None) — one row per (orientation, spacing) with mean_delta_a, mean_delta_b, mean_delta_joint, mean_synergy and an uncorrected p.
• .test_pairs(pairs, target, backgrounds, spacings, alpha=0.01) — several pairs with one Benjamini-Hochberg correction across all arrangements; returns a SynergyResult with .arrangements, .best and .significant(alpha).
• .target_readout(target), .group_logit(sequences, weights, bias) — the underlying pseudobulk logit readout.

Helpers: random_backgrounds(n, gc_content, seed), shuffled_backgrounds(sequence, n, seed), implant(background, motif, start), reverse_complement(sequence).

Assets

• describe_assets(species) — where each asset resolves from, without loading.
• resolve_model_path(species, explicit=None, download=True)
• resolve_metadata_path(species, explicit=None, download=True)
• fetch_species_assets(species) — both, downloading if needed.

Environment variables: PEAGENT_ASSET_ROOT, PEAGENT_CACHE_DIR, PEAGENT_HF_REPO, PEAGENT_HF_REVISION.

Sequence handling

• normalize_sequences(sequences) — centre-crop or centre-pad to 1,344 bp.
• encode_sequences(sequences) — one-hot encode; N becomes a uniform 0.25 vector.

Metrics

safe_auroc, safe_average_precision, safe_pearson, safe_spearman, safe_mae, binary_classification_metrics — thin wrappers that return nan instead of raising on degenerate input (single-class labels, zero variance).