Cherimoya¶
Cherimoya predicts how a variant changes chromatin accessibility in one ENCODE DNase-seq or ATAC-seq experiment: the total signal and its base-resolution profile, in human (hg38). An Altar model instance is one CATv1 experiment's ensemble of five folds.
| Kind | Container model; type = "CHERIMOYA" |
| Install | pip install altar-cherimoya (PyPI) |
| Genome builds | hg38 |
| Variant classes | Every class: SNVs, MNVs, insertions and deletions |
| Compute | An NVIDIA GPU per fold, then a CPU summary; up to 32 GB of memory per task |
| Image | riyavsinha/altar-cherimoya@sha256:2d287df8…, pinned by digest. linux/amd64, 3.4 GB compressed, pulled anonymously from Docker Hub on first use |
| Validation | Smoke-tested (Validation). Interpretation: Provisional (Interpretation) |
| Licence | MIT code; CATv1 weights CC BY 4.0 |
| Upstream | Code, Weights, Documentation |
When to use it¶
- Use Cherimoya to ask how a variant changes accessibility in one cell type or tissue that ENCODE profiled with DNase-seq or ATAC-seq. The CATv1 atlas has a model for each of 1,518 experiments.
- Each fold is a small network, about 0.6 million parameters, so scoring a cohort in many experiments costs little
GPU time. One model instance covers one experiment; add one
[models.<name>]section per experiment. - Choose ChromBPNet when you want ChromBPNet's own scores,
logfcandjsd, compared with a reference scorer. Every CATv1 experiment has a ChromBPNet model on ENCODE for the same experiment, named byannotation_accessionin the atlas metadata. - Choose a multi-track model, such as Enformer, Borzoi or AlphaGenome, to compare many assays or cell types from one model, or to reach gene expression.
- Cherimoya's scores are an Altar-defined effect with no upstream scorer to compare with (Validation).
Add it to a run¶
[models.cherimoya]
type = "CHERIMOYA"
resource_manifest = "cherimoya.resources.json" # altar-cherimoya-resources writes it
- Install the binding:
pip install altar-cherimoya. -
Pick an experiment (Choose an experiment) and fetch its five folds:
-
Name the manifest the command wrote as
resource_manifest, and name the section after the experiment: -
Set
[variants] reference_fastato an hg38 FASTA, and give the spec a[backend].
altar models cherimoya lists the columns, the configuration fields, the default image and the resource command.
Score variants with a model walks through a run.
Tutorial 1: score variants locally with Cherimoya runs this model
on five variants in a notebook.
Outputs¶
| Column | Type | Meaning | Units and reading |
|---|---|---|---|
counts_log2fc |
float | Alternate-minus-reference log2 effect on the single-track log(count + 1) head | log2; positive means the alternate allele gains accessibility |
profile_l1 |
float | L1 distance between alternate and reference softmax-normalized profile distributions | 0 to 2; larger means a bigger change in profile shape; no direction |
Each fold scores the variants, and a CPU task averages the five folds.
counts_log2fc follows the variant-effect example in Cherimoya's documentation. profile_l1 is defined by Altar:
upstream Cherimoya publishes no scalar profile score. The profiles are normalized before the distance because raw
profile logits have an arbitrary offset. The fields are not named after ChromBPNet's logfc and jsd, because they
are computed differently.
Cherimoya has no detail tables or artifacts.
Configuration¶
| Field | Type | Default | Meaning |
|---|---|---|---|
weights |
list of resource | required | One checkpoint per fold, in fold order, each with a SHA-256 digest. altar-cherimoya-resources writes them to a resource manifest. |
in_window |
integer | 2114 |
Length in bases of the sequence the model reads, centred on the variant. |
image |
text | "riyavsinha/altar-cherimoya@sha256:2d287df8…" |
The scoring image, as name@sha256:<digest>. Tags are refused. |
Fields go under [models.<name>.configuration]. A resource manifest gives weights instead: name its path as
resource_manifest in [models.<name>].
in_windowis 2,114 by default. The profile covers the central 1,000 bases. Interpretation refuses any otherin_window.imagemust be aname@sha256:<digest>reference built fromruntimes/cherimoya. Interpretation runs on its own image, whateverimagenames (Interpretation).
Inputs¶
- Genome builds: hg38 only. CATv1 checkpoints are trained on GRCh38, and the binding refuses other assemblies.
- Variant classes: every class. Altar builds the reference and alternate windows itself and checks that each REF matches the reference.
- Window:
in_windowbases, centred on the variant. The windows match Tangermeme 1.4.1'ssubstitution_effect,insertion_effectanddeletion_effect, including their right-flank trimming. - Reference:
[variants] reference_fasta. - Checkpoints: single-track only. The runtime refuses a checkpoint whose outputs are not one profile of shape
(N, 1, 1000)and one count of shape(N, 1).
Where it comes from¶
The CATv1 atlas has five-fold Cherimoya models for 1,518
ENCODE experiments (1,149 DNase-seq and 369 ATAC-seq) on Hugging Face. altar-cherimoya-resources fetch-official
downloads one experiment's five checkpoints from a pinned atlas revision, checks the checkpoint format and fold
identities, and writes cherimoya.resources.json. ENCSR000EOT is a K562 DNase-seq experiment and the one Altar's
validation used; it is not a default.
For checkpoints you have already downloaded,
altar-cherimoya-resources package --experiment-accession … --weights … --output-dir … writes the same manifest.
Repeat --weights once per fold, in fold order.
Each fold is a resource with a SHA-256 digest, and the digest is its identity. Moving the same bytes to another
location keeps every stored score. Other weights, another in_window or another image store scores under a new
identity.
Choose an experiment¶
The atlas's CATv1-metadata.tsv has one row per experiment. Its columns include experiment_accession (the
value to fetch), assay_term_name (DNase-seq or ATAC-seq), experiment_biosample_term_name (such as K562
or hepatocyte), biosample_classification (such as cell line, tissue or primary cell),
biosample_simple_summary (age, sex and treatment) and experiment_peturbed (TRUE for a treated sample; the
spelling is the atlas's). This reads the table at the revision the fetch command pins, and lists the unperturbed
K562 DNase-seq experiments:
import pandas as pd
metadata = pd.read_csv(
"https://huggingface.co/programmable-genomics/CATv1/resolve/"
"64a1d0c3e027d8b745e9772c0c770a91b06d3a5f/CATv1-metadata.tsv",
sep="\t",
)
k562 = metadata[
(metadata.experiment_biosample_term_name == "K562")
& (metadata.assay_term_name == "DNase-seq")
& ~metadata.experiment_peturbed
]
print(k562[["experiment_accession", "biosample_classification", "biosample_simple_summary"]])
It prints one experiment, ENCSR000EOT. A model reflects only the experiment it was trained on, so pick the assay and
biosample your question is about. The atlas's performance.tsv gives each experiment's validation metrics by fold.
Compute and scale¶
- GPU: each fold task asks for one NVIDIA GPU and up to 32 GB of memory; the summary task asks for 8 GB and no GPU. Recorded runs used an NVIDIA L40S. Each fold over three variants took about 58 seconds, most of it start-up.
- CPU: the runtime uses the CPU when no GPU is visible.
[backend] cpu_only = true(run spec) clears the GPU request. One fold was also scored on a CPU. - Scale: the runtime streams variants in fixed outer batches with a separate model batch, and the summary task streams rows. Memory use does not grow with the cohort.
- Image:
linux/amd64, 3.4 GB compressed. It runs PyTorch on Python 3.12. - Determinism: repeat GPU runs are not bit-identical. With TF32 on (the default), cuDNN's algorithm choice made
fold scores differ by up to 8.6e-4
counts_log2fcon an idle L40S, and up to 3.4e-3 on a shared one. Runs withNVIDIA_TF32_OVERRIDE=0, and CPU runs, are byte-identical. Compare GPU results with a tolerance.
Prioritization¶
A variant is prioritized when abs(counts_log2fc) >= 0.25. This is a screening rule, not a calibrated threshold.
What prioritized means explains how rules combine.
Interpretation¶
Interpretation is Provisional: method names, products and file layouts are expected to change. Interpret variants shows how to run a method and read its products.
Cherimoya has one method, ism_counts: in-silico saturation mutagenesis of the count head. Its only target is
counts. It replaces each of the central 400 bases of an allele's 2,114-base window by A, C, G and T in turn, and
predicts log(count + 1) for each edited sequence. A position's four scores are the changes in that prediction
minus their mean, one hypothetical score per base. Each fold scores both alleles, and a CPU task averages the folds.
This is the attribution cherimoya attribute computes in Cherimoya 0.2.0, the release the runtime pins.
| Product | File | Shape | Span around the variant's 0-based position p |
|---|---|---|---|
ism_scores |
average_{allele}_ism.npy, one per allele |
N x 4 x 400, float32, bases A, C, G, T | [p - 200, p + 200), anchor 200 |
ism_sequences |
{allele}_ism_sequences.npy, one per allele |
N x 4 x 400, int8 one-hot | as ism_scores |
- Rows follow the staged variant file, sorted by variant ID.
- Multiply
ism_scoresbyism_sequencesand sum over the bases to get each observed base's score. - An indel's
altrow uses the reference span. Elementileft of the anchor is reference basestart + i. The alternate allele follows the anchor. Elementiafter it is reference basestart + i + len(ref) - len(alt). - Interpretation runs on its own image,
riyavsinha/altar-cherimoya@sha256:85c754f5…, whateverimagethe configuration names. It refuses anin_windowother than 2,114, a variant whose window runs off its contig, and a variant whose REF does not match the reference. - Saturation mutagenesis uses no random references, so CPU runs are byte-identical. On a GPU, Cherimoya 0.2.0 computes part of the model in bfloat16. Two GPU runs differed by up to 3.9e-4, and GPU from CPU by up to 2.0e-3, against scores up to 0.25.
- Each fold runs about 1,200 forward passes per allele and variant. Three variants took about 134 seconds on an NVIDIA L40S and about 371 seconds on a CPU.
Validation¶
Validation label: Smoke-tested. Five-fold scoring runs end to end on an NVIDIA L40S and gives finite outputs,
and CPU runs and TF32-disabled GPU runs are byte-identical across images. The scores are an Altar-defined effect,
and Cherimoya has no official variant scorer to compare them with. Records:
l40s-catv1-k562-main-74be08c.json
(the default image) and
l40s-catv1-k562.json.
The ism_counts interpretation matches cherimoya attribute from Cherimoya 0.2.0 on three variants: within
1.0e-6 on a CPU, and within 5.0e-4 on an NVIDIA L40S. Record:
l40s-catv1-k562-ism-9f51da3.json.
Not validated:
- the scores against any upstream scorer, since none exists;
- any experiment other than ENCSR000EOT (K562 DNase-seq);
- a cohort larger than three variants.
The validation status table lists every model.
Limits¶
- hg38 and single-track CATv1-style checkpoints only.
profile_l1is Altar's own reduction, not an upstream Cherimoya metric.- Each model reflects one experiment. Do not use it for another cell type or assay.
- Repeat GPU runs are not bit-identical (Compute and scale).
- The prioritization rule is a screening rule, not a calibrated threshold.
Cite and licence¶
Cherimoya has no paper yet. Its authors ask you to cite the repository, jmschrei/cherimoya:
@misc{schreiber2026cherimoya,
author = {Schreiber, Jacob},
title = {Cherimoya},
year = {2026},
howpublished = {\url{https://github.com/jmschrei/cherimoya}}
}
The CATv1 models are trained on ENCODE data. ENCODE's citation guidance asks you to cite its integrative analysis and its portal papers, to acknowledge the consortium and the production laboratory of each dataset, and to give the experiment accession you used, such as ENCSR000EOT. The guidance also lists a preprint on ENCODE's uniform processing pipelines.
@article{encode2012integrated,
author = {{ENCODE Project Consortium}},
title = {An integrated encyclopedia of {DNA} elements in the human genome},
journal = {Nature},
volume = {489},
number = {7414},
pages = {57--74},
year = {2012},
doi = {10.1038/nature11247}
}
@article{luo2020encodeportal,
author = {Luo, Yunhai and Hitz, Benjamin C. and Gabdank, Idan and Hilton, Jason A. and Kagda, Meenakshi S. and
Lam, Bonita and Myers, Zachary and Sud, Paul and Jou, Jennifer and Lin, Khine and Baymuradov, Ulugbek K. and
Graham, Keenan and Litton, Casey and Miyasato, Stuart R. and Strattan, J. Seth and Jolanki, Otto and
Lee, Jin-Wook and Tanaka, Forrest Y. and Adenekan, Philip and O'Neill, Emma and Cherry, J. Michael},
title = {New developments on the {Encyclopedia of DNA Elements} ({ENCODE}) data portal},
journal = {Nucleic Acids Research},
volume = {48},
number = {D1},
pages = {D882--D889},
year = {2020},
doi = {10.1093/nar/gkz1062}
}
@article{kagda2025encodeportal,
author = {Kagda, Meenakshi S. and Lam, Bonita and Litton, Casey and Small, Corinn and Sloan, Cricket A. and
Spragins, Emma and Tanaka, Forrest and Whaling, Ian and Gabdank, Idan and Youngworth, Ingrid and
Strattan, J. Seth and Hilton, Jason and Jou, Jennifer and Au, Jessica and Lee, Jin-Wook and
Andreeva, Kalina and Graham, Keenan and Lin, Khine and Simison, Matt and Jolanki, Otto and Sud, Paul and
Assis, Pedro and Adenekan, Philip and Miyasato, Stuart and Zhong, Weiwei and Luo, Yunhai and
Myers, Zachary and Cherry, J. Michael and Hitz, Benjamin C.},
title = {Data navigation on the {ENCODE} portal},
journal = {Nature Communications},
volume = {16},
pages = {9592},
year = {2025},
doi = {10.1038/s41467-025-64343-9}
}
- Code: Cherimoya is MIT-licensed.
- Weights: the CATv1 atlas is licensed CC BY 4.0.
- Runtime image: built from
runtimes/cherimoyain the Altar repository (MIT) on a Python 3.12 base image. It bundles PyTorch, Cherimoya and Tangermeme under their own licences. It contains no weights. - Binding:
altar-cherimoyais MIT-licensed.
Python and extension¶
CherimoyaConfiguration holds weights (one ResourceReference per fold, each with a SHA-256 digest),
in_window and image. The image must be a name@sha256:<digest> reference; tags are refused.
CherimoyaConfiguration.from_resource_manifest reads the fetch command's manifest.
Models and plans is the API reference for the model interface it implements.
The scoring plan has one GPU task per fold and one CPU task that averages them. Each fold's weights are staged to a
fixed path, and the runtime reads only that path and its expected digest. The runtime loads checkpoints with
Cherimoya.load and predicts with Tangermeme's predict. The plugin is also an InterpretableModel;
altar_cherimoya.INTERPRETATION_IMAGE names the interpretation image.