Skip to content

Borzoi

Reference integration

Borzoi is an independently installed model binding with an isolated Python 3.10 / TensorFlow 2.15 runtime. It is designed for large variant analyses rather than an interactive one-variant service: Altar partitions the global variant set into deterministic, independently retryable batches, and each task streams its bounded shard through the published ensemble.

Model-instance scope

A Borzoi model instance is defined by:

  • the four content-addressed published human replicate weights;
  • content-addressed prediction parameters, GTEx target metadata, and GENCODE 41 annotation;
  • a strictly ordered selection of GTEx output indices;
  • reverse-complement and shift-ensemble settings;
  • an immutable runtime image; and
  • the content identity of the hg38 FASTA used for the run.

Resource locations are operational. Moving identical bytes between local storage, HTTPS, S3, or another supported transfer backend does not change scientific cache identity.

Result semantics

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

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

Scores are calculated independently for each of the four published replicates, then averaged, matching the official GTEx benchmark's ensemble semantics. The primary table contains one row per variant and identifies the gene/target pair with the largest absolute mean logSED. The manifest-declared gene_effects detail table preserves mean logSED and logD2 for every (variant, gene, target) tuple.

The initial prioritization predicate is abs(top_log_sed) >= 0.5. This is an explicit versioned policy, not a claim of universal biological significance; callers should select relevant tissues and may rematerialize a later policy without rerunning model inference.

Scale and execution

Outer variant batches are Altar's unit of scheduling, retry, and checkpointing. Within a task, the runtime loads one replicate at a time, streams small reference/alternate tensor batches, and accumulates per-replicate scores in transient SQLite. It never keeps four models or a job-wide result matrix in memory. Primary and detail files are routed separately through Altar's generic result stores.

The same plan can run through any execution backend that satisfies its container and GPU request. The binding contains no cluster, object-store, or model-registry client.

Current boundaries

  • The published human model and this integration are hg38-only.
  • The first runtime release accepts SNVs only. The manifest declares SNV-only variant eligibility, so batch preparation filters out and reports indels and multi-nucleotide variants, and the rest of a mixed cohort still scores. The runtime still rejects a non-SNV in a hand-staged batch. Indels stay out of scope until a versioned alignment policy is defined and validated.
  • The supported expression outputs are the 89 published GTEx tracks at original indices 7,522 through 7,610.
  • GENCODE exon mapping follows the official majority-overlap rule at Borzoi's 32-base output resolution.
  • A deployment prepares and registers all seven resources independently with SHA-256 digests. The runtime's borzoi-resources fetch-official command fetches pinned upstream assets, validates their structural invariants, and emits a content-identity manifest. borzoi-score smoke loads all four exact weights and verifies a full-shape prediction before admission to durable model storage.

Runtime images are published under commit-addressed GHCR tags, and the image workflow reports the resulting OCI digest. Model configurations use the digest form (ghcr.io/kundajelab/altar-borzoi@sha256:...), never the tag.

See the official Borzoi repository for the model implementation, published output definitions, and attribution.