ChromBPNet¶
ChromBPNet predicts how a variant changes chromatin accessibility (DNase-seq or ATAC-seq) in one cell type: the total signal and its base-resolution profile. An Altar model instance is one trained ensemble of five folds for one experiment, usually one of the ChromBPNet models ENCODE publishes.
| Kind | Container model; type = "CHROMBPNET" |
| Install | pip install altar-chrombpnet (PyPI) |
| Genome builds | Any; set by the model's files |
| Variant classes | Every class: SNVs, MNVs, insertions and deletions |
| Compute | An NVIDIA GPU per fold, then a CPU summary; up to 64 GB of memory per task |
| Image | riyavsinha/altar-chrombpnet@sha256:935bdc0e…, pinned by digest. linux/amd64, 6.1 GB compressed, pulled anonymously from Docker Hub on first use |
| Validation | Reference comparison (Validation). Interpretation: Provisional (Interpretation) |
| Licence | MIT code; ENCODE weights, no use restrictions |
| Upstream | Code, Weights, Preprint |
When to use it¶
- Use ChromBPNet to ask how a variant changes accessibility in one cell type or tissue, as ChromBPNet's own
scores,
logfcandjsd, with the reference scorer's peak calibration and peak overlap. Default scoring matches kundajelab/varscore exactly (Validation). - One model instance covers one experiment; add one
[models.<name>]section per experiment. The fetch command gets ENCODE's K562 DNase-seq ensemble, and ENCODE publishes models for many other experiments (Choose an experiment). - ChromBPNet scores every variant class, and can score variants through a model trained on another assembly, such as hg38 variants through a mouse model (Variants on another assembly). It also explains a variant's effect with DeepSHAP contributions and motif hits (Interpretation).
- Choose Cherimoya to fetch any of the 1,518 CATv1 experiments by accession, with smaller models. Its scores are an Altar-defined effect, not ChromBPNet's.
- 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.
Add it to a run¶
[models.chrombpnet]
type = "CHROMBPNET"
resource_manifest = "chrombpnet.resources.json" # altar-chrombpnet-resources writes it
- Install the binding:
pip install altar-chrombpnet. -
Fetch ENCODE's K562 DNase ensemble, or another experiment's files (Choose an experiment):
-
Name the manifest the command wrote as
resource_manifest, and name the section after the experiment: -
Set
[variants] reference_fasta, and give the spec a[backend]. For hg38 variants, also add a region source, such as[sources.regions](Prioritization). -
Prepare the model's peak files once, then score:
altar run checks that the prepared files are under <cache_dir>/staging/models/<name>/ before it reads the
cohort. When they are missing, it stops and lists the paths it looked for. Prepare model
resources covers altar prepare and recovery from a failed preparation.
altar models chrombpnet lists the columns, the configuration fields, the default image and the resource command.
Score variants with a model walks through a run.
Prepare the peak files¶
Scoring reads five per-fold peak activity distributions and a peak interval index. altar prepare builds them:
It writes the files under <cache_dir>/staging/models/k562-dnase/, in the cache, .altar by default. Score
from the same directory, or with the same cache_dir, and with the same model key and configuration. Preparation
predicts the count head over every peak, in the forward orientation by default, in batches of 2,048 peaks. It writes
preprocessing.manifest.json, which records the weights, peaks, reference and strand policy the files were built
from.
When altar run scores files altar prepare published, it checks them against the configuration:
- before reading the cohort, it compares the manifest with the configuration's weights, peaks and
average_reverse. A difference stops the run and names it. Runaltar prepareagain, then score; - each fold task and the summary task check the files again, including the reference they were prepared from;
- for a model trained on another assembly, the run passes the training reference that preparation read.
These checks change no score identity. Setting verify_preprocessing = false in
[models.<name>.run_inputs] turns them off, and the run logs a warning. Files staged without altar prepare are
scored as they are.
Every altar prepare runs the workflow again. Existing file names are not taken as evidence that the files match.
Outputs¶
| Column | Type | Meaning | Units and reading |
|---|---|---|---|
logfc |
float | Log2 fold-change between alternate and reference | log2; positive means the alternate allele gains accessibility |
jsd |
float | Jensen-Shannon divergence between allele profiles | base 2, from 0 to 1; larger means a bigger change in profile shape; no direction |
active_allele_quantile |
float | Peak-distribution quantile of the more active allele | 0 to 1; where the more active allele's predicted counts fall among the model's own peaks |
in_peak |
bool | Whether the variant lies in a called accessibility peak | true or false; null when the variants are on another assembly than the training assembly |
Each fold scores the variants, and a CPU summary task averages the five folds and adds in_peak.
logfcis the predicted fold-change of total accessibility, alternate over reference.jsdis the Jensen–Shannon distance between the two alleles' predicted profiles. It is SciPy'sjensenshannon, the square root of the divergence.active_allele_quantileis measured against the peak distributionaltar preparebuilds.in_peaksays whether the variant lies in the model's accessibility peaks.
Values are comparable only within one model instance, its assay and its cell type.
A variant the runtime cannot score keeps a row with all four fields null, and the runtime log gives the reason. This happens when the 2,114-base input window runs off the contig, and for variants on chrM.
ChromBPNet has no detail tables or artifacts.
Configuration¶
| Field | Type | Default | Meaning |
|---|---|---|---|
training_genome_build |
text | not set | The genome build the model was trained on, such as mm10. Not set means the run's own genome build. |
weights |
list of resource | required | Five bias-corrected fold models, in fold order, each with a distinct SHA-256 digest. altar-chrombpnet-resources writes them to a resource manifest. |
weights_format |
one of "h5" |
"h5" |
How the fold models are stored. h5, a Keras HDF5 file, is the only format the runtime loads. |
peaks |
resource | required | The experiment's peak set, a BED file, with a SHA-256 digest. altar prepare measures the model's activity at these peaks, and in_peak tests the variant against them. |
peaks_compression |
one of "gzip", "none" |
"gzip" |
Whether the peak set is gzipped (gzip) or plain text (none). |
motifs |
resource | not set | A TF-MoDISco motif set (HDF5) with a SHA-256 digest. Only the finemo_hits interpretation reads it. |
reference_seed |
integer | 0 |
The seed of the shuffled references the deepshap_counts interpretation compares each allele with, a whole number from 0 to 2^63 - 1. Another seed gives other contribution scores, stored under another interpretation ID. Scoring never reads it. |
image |
text | "riyavsinha/altar-chrombpnet@sha256:935bdc0e…" |
The scoring and preparation image, as name@sha256:<digest>. Tags are refused. Interpretation runs on its own pinned images. |
average_reverse |
true or false | false |
Average every prediction over the forward and reverse-complement strands. This changes every score and the peak calibration, and doubles inference. |
adjust_indel_jsd |
true or false | false |
Remove the shift an indel's length change causes before comparing the allele profiles. This changes indel jsd only. |
Fields go under [models.<name>.configuration]. A resource manifest gives weights and peaks instead: name its
path as resource_manifest in [models.<name>].
weightsare five resources, in fold order, with distinct digests.weights_formatish5.peaks_compressionisgzip(the default) ornone.average_reverseandadjust_indel_jsdare opt-in scoring policies that follow kundajelab/variant-scorer (Differences from varscore).motifsis read only by thefinemo_hitsinterpretation. The official manifest has none.reference_seedis read only by thedeepshap_countsinterpretation. It is 0 by default (Interpretation).training_genome_builddeclares the assembly the model was trained on (Variants on another assembly).imagemust be aname@sha256:<digest>reference built fromruntimes/chrombpnet. Interpretation runs on its own images, whateverimagenames (Interpretation).
verify_preprocessing, in [models.<name>.run_inputs], controls the checks of prepared files
(Prepare the peak files). It never enters the score identity.
Inputs¶
- Genome builds: any. The binding declares no limit. The model reads the run's reference at the variant.
- Variant classes: SNVs, insertions, deletions and multi-nucleotide variants.
- Window: 2,114 bases of input, centred on the variant. The profile covers the central 1,000 bases.
- Reference:
[variants] reference_fasta. The runtime reads it through a.faiindex. It reads an index beside the FASTA, or builds one in a temporary directory when there is none. - Region annotations: a region source for hg38 variants, which the prioritization rule reads (Prioritization).
Variants on another assembly¶
A ChromBPNet model can score variants on an assembly other than the one it was trained on, for example hg38 variants through a model trained on mouse (mm10) data. Declare the training assembly in the configuration:
[models.mouse-liver]
type = "CHROMBPNET"
resource_manifest = "mouse-liver/chrombpnet.resources.json"
[models.mouse-liver.configuration]
training_genome_build = "mm10"
Prepare the model with a spec whose [run] genome_build and [variants] reference_fasta are the training
assembly's. Preparation predicts activity at the model's peaks, which are training-assembly coordinates. Then
score with the variants' assembly. logfc, jsd and active_allele_quantile keep their meaning, because they
come from the model's predictions on the variants' own sequence. in_peak is stored as null, because the peaks
are on the other assembly.
Declare training_genome_build for every model not trained on hg38
Altar can enforce the preparation assembly only when the configuration declares it. An mm10 model prepared
against hg38 reads hg38 sequence at mm10 peak coordinates. Its peak distribution is then meaningless, and so is
every active_allele_quantile scored against it.
Variant identity and normalization describes variant and training assemblies for every model.
Where it comes from¶
One model needs five fold weights (Keras HDF5) and the experiment's peak set, each identified by its SHA-256
digest. altar-chrombpnet-resources fetch-official fetches ENCODE's K562 DNase ensemble (ENCODE experiment
ENCSR000EOT, model set ENCSR296UHQ). It downloads the two ENCODE archives (ENCFF574YLK, about 726 MB, and
ENCFF926SHM), checks their digests, extracts the five bias-corrected fold models and the peak set, and writes
chrombpnet.resources.json. For those two archives already downloaded,
altar-chrombpnet-resources package --model-archive … --regions-archive … --output-dir … writes the same manifest.
K562 is the fetch command's example, not a default. Any ChromBPNet model with five folds and a peak set fits the same configuration (Choose an experiment).
The weights and the peaks are identified by their digests. Moving the same bytes to another location keeps every
stored score. Other weights or peaks, another reference genome, average_reverse, adjust_indel_jsd, a training
assembly other than the run's, or another image store scores under a new identity. Images the binding lists as
equivalent reuse each other's scores (Validation). weights_format, peaks_compression,
motifs and reference_seed cannot change a score, and do not change its identity.
Choose an experiment¶
ENCODE publishes ChromBPNet models for many DNase-seq and ATAC-seq experiments, as annotations of type
ChromBPNet-model. Each annotation names the experiment it was trained on and holds two archives: models, with
the five folds, and training and test regions, with the peak set. This lists the HepG2 models and their archives:
import json
import urllib.request
def encode(path):
request = urllib.request.Request(f"https://www.encodeproject.org{path}", headers={"Accept": "application/json"})
with urllib.request.urlopen(request) as response:
return json.load(response)
search = encode(
"/search/?type=Annotation&annotation_type=ChromBPNet-model&status=released"
"&biosample_ontology.term_name=HepG2&assay_term_name=DNase-seq&assay_term_name=ATAC-seq"
"&format=json&limit=all"
)
for model in search["@graph"]:
annotation = encode(f"/annotations/{model['accession']}/?format=json")
archives = {
item["output_type"]: item["accession"]
for item in annotation["files"]
if item["output_type"] in {"models", "training and test regions"} and item["status"] == "released"
}
print(model["accession"], model["description"], archives)
Among its lines:
ENCSR006CUK ChromBPNet models trained on DNase-seq data in HepG2 (ENCSR149XIL) submitted for ChromBPNet manuscript {'training and test regions': 'ENCFF425GNN', 'models': 'ENCFF615AKY'}
ENCSR782TIO ChromBPNet models trained on DNase-seq data in HepG2 (ENCSR149XIL) {'models': 'ENCFF477WEZ'}
An experiment can have more than one annotation. Pick one that has both archives; the model needs the peak set. The
CATv1 atlas's annotation_accession column names the annotation for each of its experiments
(Cherimoya). A model reflects only the experiment it was trained on, so pick
the assay and biosample your question is about.
The fetch and package commands accept only the K562 archives. For another experiment, download its two archives
from https://www.encodeproject.org/files/<accession>/@@download/<accession>.tar.gz and extract:
- from
models, the bias-corrected fold modelsfold_<k>/model.chrombpnet_nobias.fold_<k>.<experiment>.h5, for folds 0 to 4; - from
training and test regions, the peak setpeaks.all_input_regions.<experiment>.bed.gz.
Then give them in the configuration, each with its SHA-256 digest (sha256sum prints it):
[models.hepg2-dnase]
type = "CHROMBPNET"
[models.hepg2-dnase.configuration]
weights = [
{ uri = "hepg2/fold_0/model.chrombpnet_nobias.fold_0.ENCSR149XIL.h5", digest = "sha256:<digest>" },
# ... folds 1 to 4, in order
]
peaks = { uri = "hepg2/peaks.all_input_regions.ENCSR149XIL.bed.gz", digest = "sha256:<digest>" }
Compute and scale¶
- GPU: each fold task asks for one NVIDIA GPU and up to 64 GB of memory; the summary task asks for 8 GB and no GPU. Every recorded scoring run used an NVIDIA L40S. One fold over 250,000 genome-wide variants took about 740 seconds. Five cold fold runs over 64 variants each took 10 to 13 seconds per fold, including model start-up.
- CPU:
[backend] cpu_only = true(run spec) clears the GPU request. CPU scoring has not been recorded. - Preparation: the official K562 ensemble has 196,077 peaks. Preparing it on an NVIDIA L40S took about 25 minutes and sampled 17,915 MiB of GPU memory and 4.2 GiB of host memory, so it needs a 24 GB-class GPU.
- Image:
linux/amd64, 6.1 GB compressed. It runs TensorFlow 2.8 on Python 3.9. - Determinism: repeat runs on a GPU can differ in the last digits. TensorFlow picks cuDNN convolution algorithms
by timing them, so two runs may use different ones. Recorded differences were up to 9.1e-4 in
logfc. Compare GPU results with a tolerance.
Prioritization¶
A variant is prioritized when all of these hold:
abs(logfc) >= 0.25;active_allele_quantile >= 0.05;- it is in a promoter (
region_typeispromoter), orin_peakis true, orin_peakis false andlogfc > 0.
This is a screening rule, not a calibrated threshold.
The rule reads region_type from a region annotation source. Region data exists for hg38, so a spec that scores
hg38 variants needs one, such as a [sources.regions] section with type = "regions"; see Genomic
regions. altar run and --validate stop and name the missing section. On an assembly without region
data, or for a variant with no region row, the promoter branch is unknown, and an AnnotationUnavailableWarning
says so. On another assembly than the training one, in_peak is null, so only the promoter branch can prioritize a
variant. What prioritized means explains unknown values and 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. ChromBPNet has two methods. Both
explain the count head, so counts is the only target.
| Method | Needs | Products |
|---|---|---|
deepshap_counts |
contribution_scores, predicted_profiles |
|
finemo_hits |
deepshap_counts, and a motifs resource |
motif_hits, variant_summary |
| Product | File | Shape | Span around the variant's 0-based position p |
|---|---|---|---|
contribution_scores |
average_{allele}_shap_contributions.npy, one per allele |
N x 2114, float16 | [p - 1057, p + 1057), anchor 1057 |
predicted_profiles |
average_{allele}_profiles.npy, one per allele |
N x 1000 | [p - 500, p + 500), anchor 500 |
motif_hits |
{allele}_hits/hits.tsv, one per allele |
finemo hits; peak_id is the variant's row |
as contribution_scores |
variant_summary |
variants_w_interpret_plots.tsv |
one row per variant, arrays as text | as predicted_profiles |
- Rows follow the staged variant file, sorted by variant ID.
- A contribution is the DeepSHAP value times the one-hot input, summed over the four bases, so only the observed base contributes.
- An indel's
altrow uses the reference window. Elementileft of the anchor is reference basestart + i. The alternate allele follows the anchor. Elementiafter it is reference basestart + i + len(ref) - len(alt). deepshap_counts(method 2.0.0) uses 20 dinucleotide-shuffled references per allele, drawn from a random stream seeded by the variant, the allele and thereference_seedsetting, 0 by default. Batching, row order and retries do not change them. On a CPU, two runs give the same bytes. Compare results from different devices with a tolerance.- Set
reference_seed, a whole number from 0, under[interpretations.<name>.configuration]. Another seed gives other contributions, under new interpretation IDs for both methods, and leaves every score as it is. finemo_hitsneeds a TF-MoDISco HDF5 motif set as themotifsresource. The official manifest has none; add it under[models.<name>.configuration]with its digest.
Interpretation always runs on two pinned images, whatever image the configuration names:
riyavsinha/altar-chrombpnet@sha256:7a3ec96f… and the finemo image
riyavsinha/altar-finemo@sha256:58f170e9… (3.5 GB compressed). Before staging anything, interpretation refuses a variant
off chr1 to chr22, chrX and chrY, a variant whose window runs off its contig, and a variant whose REF does not
match the reference.
Validation¶
Validation label: Reference comparison. The runtime's default scoring was compared on an NVIDIA L40S with
kundajelab/varscore at 3497f6c,
the reference implementation Altar follows, and matched it exactly on the recorded examples. The opt-in two-strand
averaging was compared with kundajelab/variant-scorer at
0e1e341. Record:
l40s-scoring-policy-parity.json.
Each image the binding lists for score reuse cites a record that compares it with an image already listed, on the
K562 DNase models, or a recorded reason for images listed before such records existed. The default image's record is
l40s-k562-dnase-main-3e3e853.json.
Seeded interpretation and non-root finemo ran on a CPU; see the interpretation
record.
Not validated:
- a comparison with an official ChromBPNet scorer as the default scoring path;
- any model other than the K562 DNase ensemble;
- scoring on a CPU, and interpretation replay on a GPU.
The validation status table lists every model.
Differences from varscore¶
| Concern | varscore | Altar | Effect |
|---|---|---|---|
| Strand | forward only | forward only by default; average_reverse = true averages both strands |
opting in changes every score and the peak calibration, and doubles inference |
| Indel JSD | direct comparison of the allele profiles | direct by default; adjust_indel_jsd = true removes the shift from the length change |
opting in changes indel jsd only |
| Variant-to-peak coordinates | queries a 0-based peak tree with the 1-based position | converts the position to 0-based | correction; in_peak can differ at peak edges |
| BED interval end | stores the exclusive end as inclusive | converts it | correction; removes one extra base from each peak |
| Chromosome names | uses the input spelling | treats 1 and chr1 as one contig |
correction; prevents false in_peak = false |
| Reusing earlier outputs | on by default | off by default | operational |
| Peak index file | pickle peaks.dnatree |
versioned JSON Lines peaks.intervals.jsonl |
security and portability |
| An invalid row in a batch | aborts the batch | scores the valid rows; the invalid row keeps null scores | operational |
None of these changes the formulas for logfc, jsd or active_allele_quantile. The two opt-in policies follow
kundajelab/variant-scorer and are part of the score identity.
Limits¶
- Scores describe one trained model, assay and cell type. Do not compare values across unrelated model instances without checking that their training and calibration match.
- The fetch and package commands cover only the K562 DNase ensemble. Other experiments' files are extracted by hand (Choose an experiment).
in_peakfrom peak indexes built by older runtimes used an off-by-one BED end and could miss unprefixed contigs such as1. Runaltar prepareagain with the current runtime before comparing or publishingin_peak.- Repeat GPU runs are not bit-identical (Compute and scale).
- Prioritization depends on region annotations (Prioritization).
- The prioritization rule is a screening rule, not a calibrated threshold.
Cite and licence¶
Cite the ChromBPNet preprint:
@article{pampari2024chrombpnet,
author = {Pampari, Anusri and Shcherbina, Anna and Kvon, Evgeny Z. and Kosicki, Michael and Nair, Surag and
Kundu, Soumya and Kathiria, Arwa S. and Risca, Viviana I. and Kuningas, Kristiina and Alasoo, Kaur and
Greenleaf, William James and Pennacchio, Len A. and Kundaje, Anshul},
title = {{ChromBPNet}: bias factorized, base-resolution deep learning models of chromatin accessibility reveal
cis-regulatory sequence syntax, transcription factor footprints and regulatory variants},
journal = {bioRxiv},
year = {2024},
doi = {10.1101/2024.12.25.630221}
}
The official models are 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 accessions you used: ENCSR000EOT, ENCSR296UHQ, ENCFF574YLK and ENCFF926SHM for the K562 ensemble. 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: kundajelab/chrombpnet is MIT-licensed.
- Weights: the official K562 models are ENCODE data. ENCODE lets anyone download, analyze and publish results from its data without restrictions.
- Runtime image: built from
runtimes/chrombpnetin the Altar repository (MIT) on thekundajelab/chrombpnetimage. It bundles TensorFlow and other third-party packages under their own licences. It contains no weights. - Binding:
altar-chrombpnetis MIT-licensed.
Python and extension¶
ChromBPNetConfiguration holds the five weights, the peaks, the optional motif set, the image, the training
assembly and the two scoring policies. ChromBPNetConfiguration.from_resource_manifest(path, **settings) reads the
fetch command's manifest. ChromBPNetRunInputs adds the reference and the settings that never enter the score
identity, such as verify_preprocessing. Their docstrings describe each field, and Models and
plans is the API reference for the model interface they implement.
The scoring plan has one GPU task per fold and one CPU task that averages the folds and adds in_peak. The
preparation plan writes the per-fold peak distributions and the peak interval index under the model's staging
directory. The plugin is also an InterpretableModel.