Quickstart¶
Go from a fresh install to a table of annotated, scored variants. There are three starts, in order of what they need:
| Start | Adds | Needs | Downloads |
|---|---|---|---|
| 1. Annotate with gnomAD and ClinVar | allele frequencies and clinical classifications | Python 3.12 or newer | a few MB of the published datasets, read in place |
| 2. Score with LegNet on the CPU | a model's predicted effect, kept in a store and reused | Docker, an x86-64 (amd64) machine, about 4 GB of free memory | the hg38 FASTA (984 MB, 3.3 GB unpacked), a 273 MB image, a 10 MB checkpoint |
| 3. GPU and hosted models | ChromBPNet, Cherimoya, Enformer, Borzoi, Sei, AlphaGenome | an NVIDIA GPU, or an API key | model weights and images of several GB |
Each start uses the commands and files of the one before it. Start 1 needs no Docker, GPU or genome.
Before you start¶
For start 1:
- Python 3.12 or newer, on Linux or macOS. If your system Python is older, uv installs
one: run
uv venv --seed --python 3.12 altar-envin place of thepython3 -m venvline below.--seedputspipin the environment, and the steps below install with it. Platform support has the details. - Network access. gnomAD and ClinVar are read from a public Google Cloud bucket, with no credentials.
Start 2 also needs:
- Docker, running and usable by your user:
docker run --rm hello-worldmust work. On Linux, the container runs as the owner of the directory it writes to, so it needs no extra setup. - An x86-64 (amd64) machine. The LegNet image is built for
linux/amd64only. On Apple silicon, Docker Desktop can run it under emulation, but that has not been tested. - About 4 GB of free memory for the scoring container.
- About 5 GB of free disk, and time to download: UCSC's hg38 genome (984 MB, 3.3 GB unpacked), the LegNet image (273 MB compressed, 960 MB unpacked, pulled anonymously from Docker Hub) and the LegNet checkpoint (10 MB).
Make a working directory and an environment for Altar:
mkdir altar-quickstart && cd altar-quickstart
python3 -m venv altar-env # any Python 3.12 or newer
source altar-env/bin/activate
1. Annotate variants with gnomAD and ClinVar¶
Install Altar and the two data bindings:
Save this list of variants as cohort.tsv. Each line is one variant: chromosome, position, REF and ALT. Its five
variants are three SNVs near SASH1 on chr6, a BRCA1 missense variant, and the CFTR ΔF508 deletion:
chr6 136273879 G A
chr6 136274004 C T
chr6 136274285 A G
chr7 117559590 ATCT A
chr17 43045712 T C
Spaces or tabs between the columns both work. The run also reads a VCF; see Give a run its variants.
Save a run spec as annotate.toml. It names the cohort and the two sources:
[run]
job_id = "first-annotation"
genome_build = "hg38"
[variants]
path = "cohort.tsv"
[sources.gnomad]
type = "gnomad"
[sources.clinvar]
type = "clinvar"
Run it:
The run writes its files to first-annotation/, a directory named after job_id.
The run reports each stage on standard error, starting each line with the spec section it belongs to, and prints a JSON summary on standard output:
[sources.gnomad] opened gnomad 4.1.1-genomes (hg38) from gs://kundajelab-altar/popfreq/gnomad-4.1.1-genomes (published, gcs) in 1.7s
[sources.clinvar] opened clinvar 20260928 (hg38) from gs://kundajelab-altar/clinvar/clinvar-20260928-hg38 (published, gcs) in 0.2s
[variants] reading cohort.tsv (trimming only, no reference genome)
[variants] read 5 variants in 0.0s
[export] annotating 5 variants with 2 sources; writing parquet to first-annotation/export
[export] wrote 5 rows to first-annotation/export in 1.2s; _columns.tsv lists its columns
done in 3.8s
altar run: warning: annotation sources may miss 1 indel: chr7:117559590:ATCT:A
It was trimmed but not left-aligned, because [variants] names no reference genome; gnomAD and ClinVar store indels left-aligned.
Set [variants] reference or reference_fasta to left-align it. Every variant is still in the export.
Only a reference genome can move an indel to its leftmost position in a repeat. ΔF508 is already written there, so both sources find it. Start 2 adds the genome.
Read the export, one Parquet table with a row per variant:
import pandas as pd
table = pd.read_parquet("first-annotation/export")
print(table[["variant_id", "gnomad_af", "clinvar_classification", "clinvar_review_stars"]].to_string(index=False))
variant_id gnomad_af clinvar_classification clinvar_review_stars
chr17:43045712:T:C NaN Pathogenic/Likely_pathogenic 2.0
chr6:136273879:G:A 0.000026 NaN NaN
chr6:136274004:C:T NaN NaN NaN
chr6:136274285:A:G NaN NaN NaN
chr7:117559590:ATCT:A 0.007884 Pathogenic 4.0
An empty value means the source has no record of that variant. Here gnomAD's genomes have no carrier of the
BRCA1 variant, and ClinVar has no submission for three of the chr6 SNVs. The table has 41 columns: every gnomAD
and ClinVar column, prioritized, and the models and sources that prioritized each row. The release and genome
build each source served are in first-annotation/export/_run_summary.json.
altar sources lists the other installed sources, and altar sources gnomad shows one source's columns and
options. Annotate variants with evidence adds Open Targets E2G links, phyloP conservation and
the other sources.
2. Score variants with LegNet on the CPU¶
LegNet predicts how a variant changes regulatory activity in a massively parallel reporter assay (MPRA). It runs on the CPU, in a Docker container.
Check the start 2 requirements first: Docker, an amd64 machine, memory and disk.
Install the binding and fetch the genome and checkpoint¶
In the same environment:
Fetch UCSC's hg38 genome and the official WTC11 checkpoint:
hg38 is the alias of grch38/ucsc/hg38, UCSC's GRCh38 FASTA, an entry of the genome registry, which Altar
ships, and legnet/wtc11 the entry wtc11 of the legnet registry, which altar-legnet installs. Each command
downloads the entry's files from pinned addresses and checks each file's SHA-256 digest. The genome takes a few
minutes. The files go into .altar/resources/sha256/ in the working directory, each named by its digest. altar resources lists the registries, altar resources legnet the entries of one, and
Find and fetch models and genomes says how to keep them elsewhere.
Score the cohort¶
Save score.toml. It adds the genome, the model and a local Docker backend to the annotation spec. It names
the genome and the checkpoint you fetched:
[run]
job_id = "first-scores"
genome_build = "hg38"
[variants]
path = "cohort.tsv"
reference = "hg38"
[models.legnet-wtc11]
resources = "legnet/wtc11"
[backend]
type = "local"
[sources.gnomad]
type = "gnomad"
[sources.clinvar]
type = "clinvar"
reference = "hg38"andresources = "legnet/wtc11"name whataltar resources fetchdownloaded. The entry gives the model's type,LEGNET, and its configuration.[models.legnet-wtc11]names the model. Its model key,legnet-wtc11, names its scores in the store: keep it the same across runs.[backend] type = "local"runs the model's containers with Docker on this machine.
The run writes to two directories. first-scores/, named after job_id, holds this run's export and scratch
files, and is safe to delete. .altar/ keeps the scores and everything else a later run can reuse, so the next
run finds the scores there, whatever its job_id.
Check the spec first. altar run --validate (Provisional) builds
everything a run needs, reads no variant, and writes no file:
Its output ends with:
the spec is valid; nothing was read or written. The run would:
read cohort.tsv (hg38, left-aligned against .altar/resources/sha256/5be01555d98347fdb3714dc84c6f77c9d8bc774adcf32c6f7a8fa06f5baf5e51)
score with [models.legnet-wtc11] (org.kundajelab.altar.model.legnet) on [backend] (local), CPU only
annotate with [sources.gnomad]: release 4.1.1-genomes on hg38
annotate with [sources.clinvar]: release 20260928 on hg38
keep scores in sqlite (.altar/scores.sqlite), and write parquet to first-scores/export
keep this run's files in first-scores, and reusable files in .altar
Then run it:
The output, abbreviated (the run also prints a line for each source it opens, as in start 1):
[variants] reading cohort.tsv (left-aligning against .altar/resources/sha256/5be01555d98347fdb3714dc84c6f77c9d8bc774adcf32c6f7a8fa06f5baf5e51)
[variants] read 5 variants in 0.3s
[models.legnet-wtc11] scoring with org.kundajelab.altar.model.legnet on [backend] (local), CPU only
[models.legnet-wtc11] 4 variants to score, in 1 batch
[models.legnet-wtc11] 1 task submitted; waiting up to 24h
[models.legnet-wtc11] 1 of 1 task running, 15s elapsed
[models.legnet-wtc11] 5 candidates, 1 set aside (1 deletion; listed in first-scores/staging/jobs/first-scores/variants/legnet-wtc11/ineligible.tsv), 0 already scored, 4 scored in 1 batch, in 40s
[export] annotating 5 variants with 2 sources; writing parquet to first-scores/export
[export] wrote 5 rows to first-scores/export in 1.6s; _columns.tsv lists its columns
done in 43s
The first run takes under a minute on top of the image pull. The run does not hash the 3.3 GB genome: its digest comes from the catalog, and the fetch left a verification record beside it. LegNet scores SNVs only, so the run sets the ΔF508 deletion aside and lists it in the file the line names. The deletion keeps its gnomAD and ClinVar columns.
Each model adds its columns under a prefix of its key and a short hash, such as
legnet_wtc11__60a71072bf29_activity_delta:
import pandas as pd
table = pd.read_parquet("first-scores/export")
delta = next(column for column in table.columns if column.endswith("_activity_delta"))
print(table[["variant_id", "gnomad_af", "clinvar_classification", delta]].to_string(index=False))
variant_id gnomad_af clinvar_classification legnet_wtc11__60a71072bf29_activity_delta
chr17:43045712:T:C NaN Pathogenic/Likely_pathogenic 0.012025
chr6:136273879:G:A 0.000026 NaN -0.001076
chr6:136274004:C:T NaN NaN 0.021149
chr6:136274285:A:G NaN NaN 0.055024
chr7:117559590:ATCT:A 0.007884 Pathogenic NaN
The three chr6 values match LegNet's validation record.
Run it again¶
The model's line and the last line of the output:
[models.legnet-wtc11] 5 candidates, 1 set aside (1 deletion; listed in first-scores/staging/jobs/first-scores/variants/legnet-wtc11/ineligible.tsv), 4 already scored, 0 scored in 0 batches, in 0.0s
done in 3.2s
Every variant is already in the store in .altar/, so no container starts. Add variants to the cohort and the
next run scores only the new ones. Deleting first-scores/ keeps the stored scores. Every machine that fetches
hg38 gets the same file, so runs that share a store reuse each other's scores.
Change a setting¶
average_reverse averages LegNet's prediction for each sequence with its prediction for the reverse complement. It
is on by default. Turn it off:
The next run scores the four SNVs again and keeps the new scores beside the old ones in the store. Remove the
setting and the run after that finds the original scores: 4 already scored. The export always holds the scores
of the settings in the spec.
3. GPU and hosted models¶
The other models install the same way and run from the same kind of spec. Each model's page has a box with its
type, its resource command, its image, and a [models.<name>] section to start from. altar models lists the
models you have installed, and altar models <type> shows one in full.
| Model | Install | Compute | Weights |
|---|---|---|---|
| ChromBPNet | pip install altar-chrombpnet |
NVIDIA GPU | altar-chrombpnet-resources fetch-official, then altar prepare (Provisional) |
| Cherimoya | pip install altar-cherimoya |
NVIDIA GPU | altar-cherimoya-resources fetch-official --experiment-accession … |
| Enformer | pip install "altar-enformer[prepare]" |
NVIDIA GPU | altar-enformer-resources fetch-official |
| Borzoi | pip install altar-borzoi |
NVIDIA GPU | altar-borzoi-resources fetch-official |
| Sei | pip install altar-sei |
NVIDIA GPU | download from Zenodo; digests on the Sei page |
| AlphaGenome | pip install altar-alphagenome |
none; it calls Google DeepMind's hosted API | none; an API key |
The GPU models need Docker with the NVIDIA Container
Toolkit
and an amd64 machine. Their images are 2.8 to 6.1 GB compressed. On a machine without a GPU, [backend] cpu_only = true
drops each task's GPU request so the model runs on the CPU, much more slowly.
Run tasks on a GPU or a cluster covers the GPU setup.
AlphaGenome reads its API key from an environment variable that the spec names; see Give a hosted model its credentials.
What prioritized means¶
Each model's columns, and its own prioritized column, describe one model under one set of settings. The
row's prioritized is true when a model's or a source's declared rule matched. It is not a pathogenicity,
causality, clinical or statistical conclusion; read what prioritized means before you
use it.
Next¶
- Tutorials: five notebooks that build one analysis. Tutorial 0 looks variants up in gnomAD, ClinVar and phyloP in a notebook, and Tutorial 1 scores them with Cherimoya on a GPU or the CPU.
- Give a run its variants: use your own VCF or TSV, and match its genome build.
- Read a run's results: the export's columns and its provenance.
- Run spec reference: every section and key.