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_effectsdetail table keeps every gene and tissue. The scores match the officialborzoi_sed.pyon 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
- Install the binding:
pip install altar-borzoi. -
Fetch the four replicate weights, the parameters, the GTEx targets and the GENCODE annotation (about 3.9 GB):
-
Name the manifest the command wrote as
resource_manifest, and choose the tracks (Choose tracks): -
Set
[variants] reference_fastato 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_indicesis required. It must be strictly increasing, so one selection always has one identity.reverse_complementandshiftsset how predictions are averaged (Inputs). The validation used their defaults.imagemust be aname@sha256:<digest>reference built fromruntimes/borzoi(Python and extension).altar_borzoi.DEFAULT_IMAGEis 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 - 1of the input and of the 523,264-base output window, as in the officialborzoi_sed.py. Bases past the contig end areN, 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, andshifts(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:
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, othershifts, 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_effectsto 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/borzoiin 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-borzoiis 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: