Skip to content

Borzoi

Borzoi predicts how a human SNV changes RNA-seq coverage of the genes around it, in the GTEx tissue tracks you select (hg38), from 524,288 bases of sequence around the variant.

Kind Container model; type = "BORZOI"
Install pip install altar-borzoi (PyPI)
Genome builds hg38
Variant classes SNVs
Compute An NVIDIA GPU per batch; up to 24 GB of memory per task
Image riyavsinha/altar-borzoi@sha256:12872cd1…, pinned by digest. linux/amd64, 3.1 GB compressed, pulled anonymously from Docker Hub on first use
Validation Upstream parity (GPU and CPU) (Validation)
Licence Apache 2.0 code; no stated weights licence
Upstream Code, Paper

When to use it

  • Use Borzoi to ask how an SNV changes the expression of each gene whose exons overlap the 523,264-base window around it, in GTEx tissues. You choose the tissues (Choose tracks).
  • The primary row names the gene and tissue with the largest effect, and the gene_effects detail table keeps every gene and tissue. The scores match the official borzoi_sed.py on both a GPU and a CPU (Validation).
  • Choose Enformer for chromatin, CAGE and transcription-factor tracks in many cell types. Borzoi's binding scores the 89 GTEx RNA-seq tracks only.
  • Choose ChromBPNet or Cherimoya for base-resolution accessibility in one experiment, and for indels. Borzoi scores SNVs only.
  • Choose AlphaGenome for a hosted model that also scores indels.

Add it to a run

[models.borzoi]
type = "BORZOI"
resource_manifest = "borzoi.resources.json"  # altar-borzoi-resources writes it

[models.borzoi.configuration]
# target_indices = [0]  # required, list of integer, unless the resource manifest gives it
  1. Install the binding: pip install altar-borzoi.
  2. Fetch the four replicate weights, the parameters, the GTEx targets and the GENCODE annotation (about 3.9 GB):

    altar-borzoi-resources fetch-official --output-dir borzoi-resources
    
  3. Name the manifest the command wrote as resource_manifest, and choose the tracks (Choose tracks):

    [models.borzoi]
    type = "BORZOI"
    resource_manifest = "borzoi-resources/borzoi.resources.json"
    
    [models.borzoi.configuration]
    target_indices = [7522]   # GTEx targets, original indices 7522 to 7610
    
  4. Set [variants] reference_fasta to an hg38 FASTA, and give the spec a [backend].

altar models borzoi lists the primary columns, the gene_effects detail table, the configuration fields, the default image and the resource command. Score variants with a model walks through a run. Select details and artifacts shows where the run keeps the detail rows.

Outputs

Column Type Meaning Units and reading
top_gene_id str Gene with largest absolute mean logSED GENCODE 41; the gene of the top gene and target pair
top_gene_name str GENCODE name of the top gene GENCODE 41
top_gene_strand str GENCODE strand of the top gene GENCODE 41
top_target_index int Original Borzoi output index 7,522 to 7,610; the GTEx target of the top pair, by original Borzoi index
top_target_id str Identifier of the top GTEx output text; a GTEx sample, such as GTEX-11EQ9-0526-SM-5A5JZ.1
top_target_label str Tissue label of the top output text; the tissue, such as RNA:liver
top_log_sed float Mean signed gene expression log2 fold change log2; positive means the alternate allele raises expression
top_log_d2 float Mean bin-level log-profile L2 distance L2 distance; no direction
n_genes_scored int Genes with exons in the prediction window count
n_effects_scored int Variant-gene-target effects emitted count; gene and target pairs scored
n_replicates int Published model replicates averaged count; always 4

For every gene whose exons overlap the 523,264-base output window, and for each selected GTEx target, the runtime computes Borzoi's gene-specific scores over the gene's exon bins:

logSED = log2(1 + sum(alternate exon-bin signal)) - log2(1 + sum(reference exon-bin signal))
logD2  = L2(log2(1 + alternate exon-bin signal), log2(1 + reference exon-bin signal))

Each of the four published replicates scores the variant, and the scores are averaged, as in the official GTEx benchmark. The primary table has one row per variant, for the gene and target with the largest absolute mean logSED.

gene_effects

A detail table, version 0.0.1: Mean official Borzoi logSED/logD2 for each variant-gene-GTEx target tuple.

Column Type Meaning
gene_id str GENCODE gene identifier
gene_name str GENCODE gene name
gene_strand str GENCODE gene strand
target_index int Original Borzoi output index
target_id str GTEx experiment identifier
target_label str GTEx tissue label
log_sed float Mean signed expression log2 fold change
log_d2 float Mean bin-level log-profile L2 distance
n_replicates int Published model replicates averaged

The table has one row per variant, gene and selected target. A variant with no gene in its window has no rows, and its n_effects_scored is 0. Read it as Read a run's results describes.

Configuration

Field Type Default Meaning
weights list of resource required The four published replicate models (HDF5), each with a distinct SHA-256 digest. altar-borzoi-resources writes them to a resource manifest.
parameters resource required Borzoi's prediction parameters, params_pred.json, with a SHA-256 digest.
target_metadata resource required The GTEx target table, targets_gtex.txt, with a SHA-256 digest.
gene_annotation resource required The GENCODE 41 gene annotation (GTF) whose exons define each gene's bins, with a SHA-256 digest.
target_indices list of integer required The GTEx targets to score, as Borzoi output indices from 7,522 to 7,610, in increasing order.
reverse_complement true or false true Average each prediction with the prediction for the reverse-complement sequence.
shifts list of integer [0] Sequence shifts, in bases, to average predictions over; each from -3 to 3, in increasing order.
image text "riyavsinha/altar-borzoi@sha256:12872cd1…" The scoring image, as name@sha256:<digest>. Tags are refused.

Fields go under [models.<name>.configuration]. A resource manifest gives weights, parameters, target_metadata and gene_annotation instead: name its path as resource_manifest in [models.<name>].

  • target_indices is required. It must be strictly increasing, so one selection always has one identity.
  • reverse_complement and shifts set how predictions are averaged (Inputs). The validation used their defaults.
  • image must be a name@sha256:<digest> reference built from runtimes/borzoi (Python and extension). altar_borzoi.DEFAULT_IMAGE is the default.

Inputs

  • Genome builds: hg38 only, the assembly of the published human model.
  • Variant classes: SNVs only. Batch preparation sets indels and multi-nucleotide variants aside and reports them, and the rest of the cohort scores. The runtime refuses a non-SNV in a batch staged some other way.
  • Window: 524,288 bases of input. The variant sits at 0-based position L/2 - 1 of the input and of the 523,264-base output window, as in the official borzoi_sed.py. Bases past the contig end are N, encoded as 0.25 in each one-hot column.
  • Reference: [variants] reference_fasta.
  • Targets: target_indices, a strictly ordered list from the 89 published GTEx tracks (original indices 7,522 to 7,610). Exons map to Borzoi's 32-base output bins by the official majority-overlap rule.
  • Ensembling: reverse_complement (default true) averages both strands, and shifts (default [0]) lists sequence shifts.

Where it comes from

A Borzoi model instance needs seven resources, each with a SHA-256 digest: the four human replicate weights (about 744 MB each), the prediction parameters, the GTEx target table and the GENCODE 41 annotation (about 926 MB). altar-borzoi-resources fetch-official fetches them from the pinned upstream locations, checks their structure and writes borzoi.resources.json. For files you have already downloaded, altar-borzoi-resources package writes the same manifest from --weight (once per replicate), --parameters, --target-metadata, --gene-annotation and --output-dir.

Inside the runtime image, borzoi-score smoke loads all four weights and checks a full-size prediction.

A model instance is defined by the seven resource digests, the ordered target selection, the two ensembling settings, the image and the reference's digest. Resource locations are not part of it, so moving the same bytes keeps every stored score.

Choose tracks

The GTEx target table, targets_gtex.txt, has one row per track, which Borzoi calls a target. Its first column, which has no header, is the original Borzoi index that target_indices takes. identifier is the GTEx sample and description is the tissue, such as RNA:liver. The 89 tracks cover 31 tissues, two or three samples each. This reads the table at the revision the fetch command pins, lists the tissues, and picks the liver tracks:

import pandas as pd

targets = pd.read_csv(
    "https://raw.githubusercontent.com/calico/borzoi/"
    "6503ea5d9f5e27a6ec6f6488c1d0a00a069cd5b0/examples/targets_gtex.txt",
    sep="\t",
    index_col=0,
)
print(targets.description.str.removeprefix("RNA:").unique())
liver = targets[targets.description == "RNA:liver"]
print(liver[["identifier", "description"]])
print(liver.index.tolist())

Its last line is the selection:

[7563, 7564, 7565]

Give that list as target_indices. The prioritization rule reads only the top pair, so its meaning depends on the tissues you select.

Compute and scale

  • GPU: each batch task asks for one NVIDIA GPU and up to 24 GB of memory. On an NVIDIA L40S, 20 variants against all 89 GTEx targets took about 6 minutes.
  • CPU: [backend] cpu_only = true (run spec) clears the GPU request. The CPU validation ran the binding's command in the default image on a CPU.
  • Scale: Altar splits the cohort into batches, and each batch is one retryable container task. Within a task, the runtime loads one replicate at a time, streams small reference and alternate batches, and keeps per-replicate scores in a temporary SQLite file. It never holds four models or the job's whole result in memory.
  • Image: linux/amd64, 3.1 GB compressed. It runs TensorFlow 2.15 on Python 3.10 with CUDA 12.2.
  • Determinism: GPU and CPU results differ slightly. TensorFlow 2.15 uses TF32 for float32 convolutions on the L40S, so L40S and CPU outputs differ by up to 7.3e-4 in logSED. Compare a GPU run with the official scorer on a GPU, and a CPU run with it on a CPU.

Prioritization

A variant is prioritized when abs(top_log_sed) >= 0.5. This is a screening rule, not a calibrated threshold. Its meaning depends on the tissues you select. What prioritized means explains how rules combine.

Validation

Validation label: Upstream parity (GPU and CPU). The default image matches the official borzoi_sed.py on 20 hg38 SNVs (532 variant-gene pairs and 47,348 gene effects across all 89 GTEx targets). It meets the criteria fixed before the comparison twice: with both scorers on a CPU, and with both on the same NVIDIA L40S. On the L40S the largest logSED difference is 6.5e-5, and every primary row names the official top gene and target. Record: l40s-official-debcb9b.json.

The record also compares an L40S run with a CPU run of the official scorer. That comparison misses the criteria, because TF32 on the GPU changes the results. The same-device comparisons are the basis of the label.

Not validated:

  • GPUs other than the NVIDIA L40S;
  • reverse_complement = false, other shifts, and target subsets other than all 89;
  • indels, which the binding does not score.

The validation status table lists every model.

Limits

  • hg38 SNVs only.
  • Expression outputs are the 89 GTEx tracks only.
  • The primary row reports one gene and target. Use gene_effects to compare genes.
  • GPU and CPU scores differ slightly (Compute and scale).
  • The prioritization rule is a screening rule, not a calibrated threshold.

Cite and licence

Cite the Borzoi paper:

@article{linder2025borzoi,
  author = {Linder, Johannes and Srivastava, Divyanshi and Yuan, Han and Agarwal, Vikram and Kelley, David R.},
  title = {Predicting {RNA}-seq coverage from {DNA} sequence as a unifying model of gene regulation},
  journal = {Nature Genetics},
  volume = {57},
  number = {4},
  pages = {949--961},
  year = {2025},
  doi = {10.1038/s41588-024-02053-6}
}
  • Code: calico/borzoi and calico/baskerville-tf are licensed Apache 2.0.
  • Weights: the published replicate weights are linked from the calico/borzoi repository, which states no separate licence for them.
  • Runtime image: built from runtimes/borzoi in the Altar repository (MIT) on NVIDIA's CUDA 12.2 runtime image, with Borzoi and Baskerville at pinned revisions. It bundles TensorFlow and other third-party packages under their own licences, and CUDA under NVIDIA's terms. It contains no weights.
  • Binding: altar-borzoi is MIT-licensed.

Python and extension

BorzoiConfiguration holds weights (four resources), parameters, target_metadata, gene_annotation, target_indices, reverse_complement, shifts and image. BorzoiConfiguration.from_resource_manifest reads the fetch command's manifest, and altar_borzoi.DEFAULT_IMAGE is the default image. Models and plans is the API reference for the model interface it implements.

The scoring plan has one GPU task per batch. Primary and detail files go to the run's score store and detail store.

To use your own image, build it from the repository root, push it, and set image to the pushed digest (<registry>/altar-borzoi@sha256:…), never the tag:

docker build --platform linux/amd64 -f runtimes/borzoi/Dockerfile -t <registry>/altar-borzoi:<tag> .
docker push <registry>/altar-borzoi:<tag>