Skip to content

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, logfc and jsd, compared with a reference scorer. Every CATv1 experiment has a ChromBPNet model on ENCODE for the same experiment, named by annotation_accession in 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
  1. Install the binding: pip install altar-cherimoya.
  2. Pick an experiment (Choose an experiment) and fetch its five folds:

    altar-cherimoya-resources fetch-official --experiment-accession ENCSR000EOT --output-dir cherimoya-resources
    
  3. Name the manifest the command wrote as resource_manifest, and name the section after the experiment:

    [models.k562-dnase]
    type = "CHERIMOYA"
    resource_manifest = "cherimoya-resources/cherimoya.resources.json"
    
  4. Set [variants] reference_fasta to 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_window is 2,114 by default. The profile covers the central 1,000 bases. Interpretation refuses any other in_window.
  • image must be a name@sha256:<digest> reference built from runtimes/cherimoya. Interpretation runs on its own image, whatever image names (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_window bases, centred on the variant. The windows match Tangermeme 1.4.1's substitution_effect, insertion_effect and deletion_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_log2fc on an idle L40S, and up to 3.4e-3 on a shared one. Runs with NVIDIA_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_scores by ism_sequences and sum over the bases to get each observed base's score.
  • An indel's alt row uses the reference span. Element i left of the anchor is reference base start + i. The alternate allele follows the anchor. Element i after it is reference base start + i + len(ref) - len(alt).
  • Interpretation runs on its own image, riyavsinha/altar-cherimoya@sha256:85c754f5…, whatever image the configuration names. It refuses an in_window other 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_l1 is 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/cherimoya in 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-cherimoya is 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.