Skip to content

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, logfc and jsd, 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
  1. Install the binding: pip install altar-chrombpnet.
  2. Fetch ENCODE's K562 DNase ensemble, or another experiment's files (Choose an experiment):

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

    [models.k562-dnase]
    type = "CHROMBPNET"
    resource_manifest = "chrombpnet-resources/chrombpnet.resources.json"
    
  4. Set [variants] reference_fasta, and give the spec a [backend]. For hg38 variants, also add a region source, such as [sources.regions] (Prioritization).

  5. Prepare the model's peak files once, then score:

    altar prepare spec.toml --model k562-dnase
    altar run spec.toml
    

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:

altar prepare spec.toml --model k562-dnase --validate
altar prepare spec.toml --model k562-dnase

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. Run altar prepare again, 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.

  • logfc is the predicted fold-change of total accessibility, alternate over reference.
  • jsd is the Jensen–Shannon distance between the two alleles' predicted profiles. It is SciPy's jensenshannon, the square root of the divergence.
  • active_allele_quantile is measured against the peak distribution altar prepare builds.
  • in_peak says 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>].

  • weights are five resources, in fold order, with distinct digests. weights_format is h5.
  • peaks_compression is gzip (the default) or none.
  • average_reverse and adjust_indel_jsd are opt-in scoring policies that follow kundajelab/variant-scorer (Differences from varscore).
  • motifs is read only by the finemo_hits interpretation. The official manifest has none.
  • reference_seed is read only by the deepshap_counts interpretation. It is 0 by default (Interpretation).
  • training_genome_build declares the assembly the model was trained on (Variants on another assembly).
  • image must be a name@sha256:<digest> reference built from runtimes/chrombpnet. Interpretation runs on its own images, whatever image names (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 .fai index. 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 models fold_<k>/model.chrombpnet_nobias.fold_<k>.<experiment>.h5, for folds 0 to 4;
  • from training and test regions, the peak set peaks.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_type is promoter), or in_peak is true, or in_peak is false and logfc > 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 alt row uses the reference window. 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).
  • 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 the reference_seed setting, 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_hits needs a TF-MoDISco HDF5 motif set as the motifs resource. 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_peak from peak indexes built by older runtimes used an off-by-one BED end and could miss unprefixed contigs such as 1. Run altar prepare again with the current runtime before comparing or publishing in_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/chrombpnet in the Altar repository (MIT) on the kundajelab/chrombpnet image. It bundles TensorFlow and other third-party packages under their own licences. It contains no weights.
  • Binding: altar-chrombpnet is 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.