README.md

---
license: cc-by-4.0
pipeline_tag: other
tags:
- genomics
- chromatin-accessibility
- atac-seq
- dnase-seq
- sequence-to-function
- encode
---

# Cherimoya Accessibility aTlas (CATv1)

This is the first release of the **Cherimoya Accessibility aTlas (CATv1)**: a collection of over 7,500 Cherimoya models trained on DNase-seq and ATAC-seq experiments from the ENCODE Project. Cherimoya models are state-of-the-art predictors of local chromatin accessibility, mapping a DNA sequence to a base-resolution accessibility profile together with its total read count.

This release covers **1,518 ENCODE experiments** (1,149 DNase-seq and 369 ATAC-seq). Every experiment is trained and evaluated across **5 folds** (`fold_0`–`fold_4`) of a chromosome-held-out cross-validation. Each model predicts accessibility for a **single experiment**, so download only the model(s) you need.

## Model description

Each Cherimoya model is a compact residual convolutional network (~0.6M parameters; 9 layers, 128 filters) in the BPNet / ChromBPNet family. It takes a one-hot DNA sequence of `in_window=2114` bp and produces two outputs over the central `out_window=1000` bp: a **profile** head (base-resolution logits, shape `(N, 1, 1000)`) describing the shape of the accessibility signal, and a **count** head (log total counts, shape `(N, 1)`) describing the overall magnitude. The published checkpoints are the exponential-moving-average (EMA) shadow weights selected on validation performance.

See https://github.com/jmschrei/cherimoya for more details on the Cherimoya model.

## Training data

Models are trained on the human genome (**GRCh38 / hg38**) against the observed ENCODE accessibility signal for each experiment. Training loci are the experiment's peak regions plus GC-matched background (non-peak) negatives, with ENCODE blacklist regions excluded. The five folds partition the genome by chromosome, so for every fold the validation and test chromosomes are held out of training; reported metrics are **validation-set** performance, not the test set.

## Repository layout

Checkpoints live under `models/`, one directory per experiment:

| file | description |
|---|---|
| `models/<encid>/cherimoya.fold_<i>.torch` | checkpoint for fold `i` (EMA shadow weights) |

Repository-level files:

| file | description |
|---|---|
| `performance.tsv` | validation metrics for every experiment and fold |
| `CATv1-metadata.tsv` | experiment metadata, keyed by `experiment_accession` |
| `manifest.csv` | the full list of experiments and folds included |
| `fit.json` / `evaluate.json` | a representative example of the per-fold training / evaluation settings |

`performance.tsv` has one row per experiment-fold: the first two columns are `experiment_accession` and `fold`, followed by `profile_mnll profile_jsd profile_pearson profile_spearman count_pearson count_spearman count_mse`. The headline metrics are `profile_pearson` (profile shape) and `count_pearson` (total accessibility).

Each `experiment_accession` is the source ENCODE experiment the models were trained on (`https://www.encodeproject.org/experiments/<experiment_accession>/`), and the paired `annotation_accession` points to the ENCODE ChromBPNet model annotation for that same experiment (`https://www.encodeproject.org/annotations/<annotation_accession>/`).

## Which model should I use?

Pick the experiment that matches your assay and biosample using `CATv1-metadata.tsv`, then download that experiment's checkpoint(s). The five folds are cross-validation replicates of the same experiment: use a single fold (e.g. `fold_0`), or average the predictions of all five folds for a more robust estimate. A model only reflects the experiment it was trained on, so do not use it for a different cell type or assay.

## Intended uses and limitations

Beyond profile and count prediction, the models support downstream sequence analyses such as attribution, motif marginalization, and in-silico mutagenesis. They are **human (GRCh38) only**, are specific to the experiment they were trained on, and report validation (not test) metrics.

## Installation

```bash
pip install cherimoya    # PyPI (Python 3.10+)
```

Install-from-source, Docker images, and GPU/Triton notes: https://github.com/jmschrei/cherimoya

## Usage

```python
import torch
from huggingface_hub import hf_hub_download
from cherimoya import Cherimoya

path = hf_hub_download("programmable-genomics/CATv1", "models/<encid>/cherimoya.fold_0.torch")
model = Cherimoya.load(path, device="cuda", compile=False).eval()

# Input: one-hot DNA, shape (batch, 4, in_window=2114), ACGT channels.
X = torch.zeros(2, 4, 2114, device="cuda")
X[:, 0] = 1.0   # placeholder: replace with your encoded sequences

# Option A: call the model directly.
profile_logits, log_counts = model(X)          # (N,1,1000), (N,1)
profile = torch.softmax(profile_logits.float(), dim=-1)

# Option B: via tangermeme (auto-batches, handles device/dtype).
from tangermeme.predict import predict
profile_logits, log_counts = predict(model, X, device="cuda", batch_size=64)
```

## Contact

Jacob Schreiber <jacob.schreiber@umassmed.edu> — Programmable Genomics Laboratory @ UMass Chan.