Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,83 @@
+---
+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 1,000 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.
+
+## 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 chromosomes are held out of training; reported metrics are therefore **validation-set** performance, not a separate test set.
+
+## Repository layout
+
+Files are organized one directory per experiment, `<encid>/`:
+
+| file | description |
+|---|---|
+| `cherimoya.fold_<i>.torch` | the model checkpoint (EMA shadow weights) |
+| `cherimoya.fold_<i>.performance.tsv` | validation metrics for that fold |
+| `cherimoya.fold_<i>.log` | training log |
+| `cherimoya.fold_<i>.fit.json` / `.evaluate.json` | training / evaluation settings |
+
+`performance.tsv` has one row with columns (fixed order): `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).
+
+Experiment-level metadata is in `CATv1-metadata.tsv` (keyed by `experiment_accession`), and `manifest.csv` lists exactly which experiments and folds are included. 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", "<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.