Cherimoya

License: Cherimoya uses MIT for code and CC-BY-4.0 for model weights and may require explicit attribution when utilized. Please refer to the code license and model weights license for full terms.

Proto is not affiliated with UMass Chan Medical School. This toolkit is open source and builds on the implementation produced by this organization. Product names, logos, and trademarks are the property of their respective owners.

GitHub 70 GitHub 70

HuggingFace

HuggingFace Publication Publication Cite Cite Tool Source Tool Source Open as Notebook Open as Notebook Open on Proto Open on Proto

jmschrei/cherimoya

Cherimoya is a lightweight sequence-to-function (S2F) model that is small, fast, and easy to use. Now usable by agents.

70 stars

View repo

programmable-genomics/CATv1

View model

Cherimoya: a lightweight genomic sequence-to-function model built for large-scale design and understanding

Christian Ramirez, Achsah Marlene Aruva, … Jacob Schreiber

Nature (2026)

Read paper

@miscramirez2026cherimoya@articleencode2020expanded

@misc{ramirez2026cherimoya,
  title={Cherimoya: a lightweight genomic sequence-to-function model built for large-scale design and understanding},
  author={Ramirez, Christian and Aruva, Achsah Marlene and Weng, Zhiping and Schreiber, Jacob},
  howpublished={Genomics x AI Blog},
  year={2026},
  doi={10.5281/zenodo.21535161},
  url={https://genomicsxai.github.io/blogs/2026-011/}
}

@article{encode2020expanded,
  title={Expanded encyclopaedias of DNA elements in the human and mouse genomes},
  author={{ENCODE Project Consortium} and Moore, Jill E. and Purcaro, Michael J. and Pratt, Henry E. and Epstein, Charles B. and Shoresh, Noam and Adrian, Jessika and Kawli, Trupti and Davis, Carrie A. and Dobin, Alexander and others},
  journal={Nature},
  volume={583},
  pages={699--710},
  year={2020},
  doi={10.1038/s41586-020-2493-4},
  url={https://doi.org/10.1038/s41586-020-2493-4}
}

Copy citation

evo-design/proto-tools

Toolkit contributors

Function	Description
`run_cherimoya_catalog()`	Search the ENCODE DNase-seq and ATAC-seq experiments a Cherimoya collection has models for	Docs Source
`run_cherimoya_gradient()`	Compute differentiable Cherimoya accessibility losses and gradients for relaxed DNA logits (GPU)	Docs Source
`run_cherimoya_predict()`	Predict base-resolution DNase-seq or ATAC-seq profiles with Cherimoya (CATv1) models (GPU)	Docs Source
`run_cherimoya_score()`	Predict DNase-seq or ATAC-seq read counts for DNA sequences with Cherimoya (CATv1) models (GPU)	Docs Source

Background

Cherimoya (Ramirez et al., 2026) adapts the BPNet/ChromBPNet architecture into a residual convolutional network of about 614,000 parameters. It takes one-hot DNA of 2,114 bp and predicts two quantities over the central 1,000 bp: a profile head (the shape of the read distribution, one value per base) and a count head (ln of the total reads plus one). Multiplying the softmaxed profile by the expected total gives predicted reads per base. CATv1 is the Cherimoya Accessibility aTlas, v1: models trained on 1,149 DNase-seq and 369 ATAC-seq experiments from the ENCODE Project, on GRCh38, across 407 biosamples. Each experiment has five models, one per chromosome-held-out cross-validation fold. A model reflects only the assay and biosample of the experiment it was trained on, so pick experiments with cherimoya-catalog rather than by cell type name alone.

Learning Resources

Cherimoya: a lightweight genomic sequence-to-function model built for large-scale design and understanding (Genomics x AI) - the announcement post introducing the model, the CATv1 atlas, and the design workflows they are built for.
jmschrei/cherimoya (Programmable Genomics Laboratory) - the reference implementation, with the model code and training scripts.
CATv1 model weights (Hugging Face) - the released checkpoints this toolkit loads, one per ENCODE experiment and fold.

Tools

Cherimoya Catalog (`cherimoya-catalog`)

Searches the experiments in a collection by biosample, assay, biosample classification, accession, and validation performance, and marks one default experiment per (assay, biosample).

API Reference

Source

Input: CherimoyaCatalogInput

string

Case-insensitive regular expression matched against the biosample term name and summary, e.g. "K562" or "hepat|liver".

string

Restrict to "DNase-seq" or "ATAC-seq".

array

Restrict to these ENCODE biosample classifications.

array

Restrict to these experiment accessions.

boolean

default:"False"

Return only the default experiment of each (assay, biosample), as Chorus committed it. Four of the 492 defaults are experiments ENCODE marks as perturbed; they are returned whatever include_perturbed says.

boolean

default:"False"

Include experiments ENCODE marks as perturbed. Accessions named in accessions are always returned.

number

Minimum fold 0 validation count Pearson.

integer

default:"50"

Maximum number of experiments to return, best count Pearson first.

Source

Config: CherimoyaCatalogConfig

string

default:"catv1"

Collection to search.

integer

default:"0"

Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). True is coerced to 1 and False to 0.

string

default:"cpu"

Device to run the tool on.

integer

default:"3600"

Maximum execution time in seconds. None waits indefinitely.

integer

Random seed. When set, tools run reproducibly up to small GPU float noise (see BaseToolOutput.approx_equal), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source

Output: CherimoyaCatalogOutput

List[CherimoyaCatalogEntry]

required

Matches, best fold 0 count Pearson first.

Show CherimoyaCatalogEntry

string

required

Collection the experiment belongs to.

string

required

ENCODE experiment the models were trained on.

string

required

ENCODE ChromBPNet model annotation for the same experiment.

string

required

"DNase-seq" or "ATAC-seq".

string

required

ENCODE biosample term name.

string

required

Ontology term ID of the biosample.

string

required

ENCODE biosample classification.

string

required

ENCODE biosample summary (donor sex and age, treatment).

boolean

required

Whether ENCODE marks the experiment as perturbed.

number

required

Fold 0 validation Pearson of log total counts.

number

required

Fold 0 validation Pearson of the base-resolution profile.

number

required

Count Pearson averaged over the five folds.

number

required

Profile Pearson averaged over the five folds.

boolean

required

Whether this is the default experiment for its (assay, biosample).

string

required

Why it is the default (Chorus rule); empty when not a default.

string

required

ENCODE portal page of the experiment.

integer

required

Matches before limit was applied.

string

required

Collection searched.

string

required

Hugging Face revision the collection’s checkpoints are pinned to.

Applications

Use this tool to find which ENCODE experiments have models for a cell type or tissue before scoring, to choose between several experiments of the same biosample, and to look up the assay and biosample behind an accession.

Usage Tips

The biosample filter is a regular expression. It is case-insensitive and matches the biosample term name and summary, so hepat|liver finds hepatocytes and liver tissue.
Defaults come from Chorus. is_default marks the experiment Chorus resolves an (assay, biosample) to: the best fold 0 count Pearson, except 9 pairs pinned to the experiment behind Chorus’s ChromBPNet models.
Perturbed experiments are hidden from searches by default. Set include_perturbed=True to see the 8 that ENCODE marks as perturbed; named accessions and defaults_only results are returned either way, and 4 of the defaults (MCF-7, NAMALWA, SK-N-SH and WI38 DNase-seq) are perturbed experiments.

Cherimoya Score (`cherimoya-score`)

Predicts total accessibility for DNA sequences with one or more models and returns log counts over the 1,000 bp output window, plus expected reads inside a target range when one is given.

API Reference

Source

Input: CherimoyaSequenceInput

List[SequenceWindow]

required

DNA sequence(s), each with an optional target_range; a bare string is accepted. N is encoded as all zeros.

Show SequenceWindow

string

required

DNA sequence — an exact model-context window, or a longer source sequence paired with target_range.

SequenceTargetRange

Optional sequence-relative span the tool must keep inside the model output bins. Windowing is all-or-nothing across a call: set target_range on every window or on none (see :func:windows_target_ranges).

Source

Config: CherimoyaScoreConfig

integer

default:"0"

Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). True is coerced to 1 and False to 0.

string

default:"cuda"

Device used for inference.

integer

default:"3600"

Maximum execution time in seconds. None waits indefinitely.

integer

string

default:"catv1"

Collection the accessions in models come from.

List[string]

default:"['ENCSR000EOT']"

ENCODE experiment accessions from the collection, or paths to Cherimoya .torch checkpoints with the same 2,114 bp in, 1,000 bp out geometry.

List[integer]

default:"[0]"

Folds to load for each accession; several are averaged. A checkpoint path is one model and ignores folds.

boolean

default:"False"

Average forward and reverse-complement predictions.

integer

default:"64"

Sequences per forward pass.

Source

Output: CherimoyaScoreOutput

List[CherimoyaScoreResult]

required

Per-sequence scores.

Show CherimoyaScoreResult

List[CherimoyaScoreMetrics]

required

One entry per requested model, in config order.

string

required

Input DNA sequence.

integer

required

Length of the input sequence.

integer

required

Start of the 2,114 bp model input window.

integer

required

End of the model input window.

integer

required

Start of the 1,000 bp span the model predicts.

integer

required

End of the predicted span.

integer

Requested target start, if target_range was set.

integer

Requested target end, if target_range was set.

List[CherimoyaModelInfo]

required

Provenance of each model, in config order.

Show CherimoyaModelInfo

string

required

ENCODE experiment accession, or the checkpoint path for a custom model.

string

Collection of a catalog model; None for a checkpoint path.

string

Hugging Face revision the checkpoints were downloaded at.

string

Assay the model was trained on, when known from the catalog.

string

Biosample the model was trained on, when known from the catalog.

List[integer]

Folds loaded for this model; empty for a checkpoint path.

List[string]

SHA-256 of each checkpoint file, in fold order.

boolean

required

Whether strands were averaged.

Metrics (one set per results item)

Metric	Type	Range	Availability
`log_counts`	float	unbounded	always
`target_counts`	float	unbounded	when target_range is set

Applications

Use this tool to rank regulatory element designs by predicted DNase-seq or ATAC-seq signal in a chosen biosample, compare a sequence across many cell types at once, or screen candidates before profiling them.

Usage Tips

Sequences are 2,114 bp windows. Pass exactly 2,114 bp, or a longer sequence with a target_range of at most 1,000 bp and the tool cuts the window.
Compare experiments with care. Raw log counts scale with each experiment’s sequencing depth, so the same value means different things in two experiments.
Folds and strands are options. The default runs fold 0; list more folds to average them, and set reverse_complement_average=True to average both strands.

Cherimoya Predict (`cherimoya-predict`)

Predicts a base-resolution accessibility profile over the 1,000 bp output window for each sequence and model.

API Reference

Source

Input: CherimoyaSequenceInput

List[SequenceWindow]

required

DNA sequence(s), each with an optional target_range; a bare string is accepted. N is encoded as all zeros.

Show SequenceWindow

string

required

DNA sequence — an exact model-context window, or a longer source sequence paired with target_range.

SequenceTargetRange

Source

Config: CherimoyaPredictConfig

enum

default:"expected_counts"

"expected_counts" returns predicted reads per base; "probabilities" returns the profile shape, which sums to 1.Available options: expected_counts, probabilities

integer

default:"0"

Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). True is coerced to 1 and False to 0.

string

default:"cuda"

Device used for inference.

integer

default:"3600"

Maximum execution time in seconds. None waits indefinitely.

integer

string

default:"catv1"

Collection the accessions in models come from.

List[string]

default:"['ENCSR000EOT']"

ENCODE experiment accessions from the collection, or paths to Cherimoya .torch checkpoints with the same 2,114 bp in, 1,000 bp out geometry.

List[integer]

default:"[0]"

Folds to load for each accession; several are averaged. A checkpoint path is one model and ignores folds.

boolean

default:"False"

Average forward and reverse-complement predictions.

integer

default:"64"

Sequences per forward pass.

Source

Output: CherimoyaPredictOutput

List[CherimoyaPredictionResult]

required

Per-sequence profiles.

Show CherimoyaPredictionResult

List[CherimoyaProfile]

required

One profile per requested model, in config order.

string

required

Input DNA sequence.

integer

required

Length of the input sequence.

integer

required

Start of the 2,114 bp model input window.

integer

required

End of the model input window.

integer

required

Start of the 1,000 bp span the model predicts.

integer

required

End of the predicted span.

integer

Requested target start, if target_range was set.

integer

Requested target end, if target_range was set.

List[CherimoyaModelInfo]

required

Provenance of each model, in config order.

Show CherimoyaModelInfo

string

required

ENCODE experiment accession, or the checkpoint path for a custom model.

string

Collection of a catalog model; None for a checkpoint path.

string

Hugging Face revision the checkpoints were downloaded at.

string

Assay the model was trained on, when known from the catalog.

string

Biosample the model was trained on, when known from the catalog.

List[integer]

Folds loaded for this model; empty for a checkpoint path.

List[string]

SHA-256 of each checkpoint file, in fold order.

string

required

What the profile values are ("expected_counts" or "probabilities").

boolean

required

Whether strands were averaged.

Applications

Use this tool to see where accessibility falls within an element, compare the profile shape between cell types, or plot predicted signal next to measured tracks.

Usage Tips

Choose the values. values="expected_counts" returns predicted reads per base and values="probabilities" returns the profile shape, which sums to 1.
Profiles cover the output window only. Each profile spans output_start to output_end of the input sequence, the central 1,000 bp of the 2,114 bp context.

Cherimoya Gradient (`cherimoya-gradient`)

Computes a weighted differentiable accessibility objective over one or more models and, by default, returns its gradient with respect to batched relaxed DNA logits.

API Reference

Source

Input: CherimoyaGradientInput

List[array]

required

Batched relaxed DNA logits with shape (B, L, 4) in A,C,G,T order, for the designed segment only. Use B=1 for one candidate.

number

default:"1.0"

Softmax temperature used to relax logits.

Source

Config: CherimoyaGradientConfig

string

default:"catv1"

Collection the accessions in loss_terms come from.

List[CherimoyaGradientLossTerm]

Objective terms summed into one loss.

Show CherimoyaGradientLossTerm

string

default:"ENCSR000EOT"

ENCODE experiment accession or local .torch checkpoint path.

List[integer]

default:"[0]"

Folds averaged for this term (ignored for a checkpoint path).

enum

default:"log_counts"

"log_counts", ln(reads + 1) over the 1,000 bp output window, or "log_target_counts", ln(expected reads + 1) in the config’s target span.Available options: log_counts, log_target_counts

enum

default:"max"

"max" minimizes 1 - sigmoid((value - center) / scale); "min" minimizes sigmoid((value - center) / scale).Available options: max, min

number

default:"1.0"

Non-negative scalar applied before terms are summed.

number

default:"4.5"

Value of quantity where the sigmoid is 0.5.

number

default:"1.0"

Positive scale of the sigmoid in quantity units.

string

default:""

Fixed DNA placed before the designed segment.

string

default:""

Fixed DNA placed after the designed segment.

integer

Start of the log_target_counts span, relative to the designed segment; None means its start.

integer

End of the log_target_counts span, relative to the designed segment; None means its end.

boolean

default:"False"

Average forward and reverse-complement predictions.

number

default:"1.0"

Blend hard argmax one-hot (0) to softmax probabilities (1).

number

default:"0.0"

Straight-through hard-forward coefficient.

boolean

default:"True"

Run the backward pass and return the gradient.

boolean

default:"False"

Use plain PyTorch kernels so repeated gradients are bit-identical.

integer

default:"0"

Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). True is coerced to 1 and False to 0.

string

default:"cuda"

Device used for inference and backpropagation.

integer

default:"3600"

Maximum execution time in seconds. None waits indefinitely.

integer

Source

Output: CherimoyaGradientOutput

List[CherimoyaGradientSampleMetrics]

Per-sample loss and term values.

Show CherimoyaGradientSampleMetrics

List[Dict[string, any]]

Per-term model, quantity value, sigmoid transform, and weighted score for this sample.

string

Name of the metric that best summarizes the result overall (e.g. "avg_plddt" for AlphaFold2). Used by downstream UI and reporting to pick a headline value.

string

Concrete Metrics subclass tag; enables typed reconstruction after a serialization round-trip.

List[CherimoyaModelInfo]

Provenance of each model the terms used.

Show CherimoyaModelInfo

string

required

ENCODE experiment accession, or the checkpoint path for a custom model.

string

Collection of a catalog model; None for a checkpoint path.

string

Hugging Face revision the checkpoints were downloaded at.

string

Assay the model was trained on, when known from the catalog.

string

Biosample the model was trained on, when known from the catalog.

List[integer]

Folds loaded for this model; empty for a checkpoint path.

List[string]

SHA-256 of each checkpoint file, in fold order.

array

Gradient matching the input logits, or None when compute_gradient=False.

number

required

Sum of per-sample weighted objective values.

Dict[string, any]

Auxiliary payload from the worker.

List[string]

required

DNA column ordering for logits and gradient.

Metrics

Metric	Type	Range	Availability
`loss`	float	≥ 0.0	always

Applications

Use this tool inside gradient-based DNA design loops, for example to raise accessibility in one biosample while lowering it in others. It is designed for optimizer calls rather than final biological validation.

Usage Tips

Context fills the window. context_left, the designed logits, and context_right must total 2,114 bp; only the designed segment receives a gradient.
Set the sigmoid per model. Both quantities are ln(reads + 1), log_counts over the output window and log_target_counts over target_start..target_end, and both depend on each experiment’s depth; the default sigmoid_center of 4.5 is the median log_counts of the default model over hg38 cCREs.
Use deterministic=True for reproducible gradients. The default Triton kernels are faster but do not repeat bit-for-bit on GPU.

Toolkit Notes

These apply to every Cherimoya tool in this toolkit (cherimoya-catalog, cherimoya-score, cherimoya-predict, cherimoya-gradient).

Models are named by ENCODE experiment accession. models (and each gradient loss term’s model) takes accessions such as ENCSR000EOT (K562 DNase-seq), validated against the bundled catalog.
Your own checkpoints work locally. A path to a Cherimoya .torch file with the same 2,114 bp in, 1,000 bp out geometry, no control tracks, and one output can stand in for an accession; remote devices reject paths.
Weights download on first use. Each fold checkpoint (about 2.5 MB) is fetched from Hugging Face at a pinned revision into the managed model cache, and loaded checkpoints stay in the worker between calls.
Human GRCh38 only. Every CATv1 model was trained on human ENCODE data; for another species, any model is a proxy.
Runs on CPU or GPU. A GPU is much faster; on CPU expect tens of sequences per second per model.

Example notebook: See the full working example for a copy-paste-ready walkthrough.

Infrastructure Guides

The following guides cover how to run tools efficiently and at scale.

Tool Persistence

Keep a tool’s model warm across calls instead of reloading it every invocation.

Device Management

How GPUs are allocated to tools and how to target specific devices.

Parallel Execution

Fan a batch of inputs out across multiple GPUs.

Tools

Guides

Tool Catalog

Concepts

Implementing a Tool

Background

Learning Resources

Tools

Cherimoya Catalog (`cherimoya-catalog`)

API Reference

Applications

Usage Tips

Cherimoya Score (`cherimoya-score`)

API Reference

Applications

Usage Tips

Cherimoya Predict (`cherimoya-predict`)

API Reference

Applications

Usage Tips

Cherimoya Gradient (`cherimoya-gradient`)

API Reference

Applications

Usage Tips

Toolkit Notes

Infrastructure Guides

Tool Persistence

Device Management

Parallel Execution

​Background

​Learning Resources

​Tools

​Cherimoya Catalog (cherimoya-catalog)

​API Reference

​Applications

​Usage Tips

​Cherimoya Score (cherimoya-score)

​API Reference

​Applications

​Usage Tips

​Cherimoya Predict (cherimoya-predict)

​API Reference

​Applications

​Usage Tips

​Cherimoya Gradient (cherimoya-gradient)

​API Reference

​Applications

​Usage Tips

​Toolkit Notes

​Infrastructure Guides

Tool Persistence

Device Management

Parallel Execution

Background

Learning Resources

Tools

Cherimoya Catalog (`cherimoya-catalog`)

API Reference

Applications

Usage Tips

Cherimoya Score (`cherimoya-score`)

API Reference

Applications

Usage Tips

Cherimoya Predict (`cherimoya-predict`)

API Reference

Applications

Usage Tips

Cherimoya Gradient (`cherimoya-gradient`)

API Reference

Applications

Usage Tips

Toolkit Notes

Infrastructure Guides