Skip to content

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-env in place of the python3 -m venv line below. --seed puts pip in 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-world must 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/amd64 only. 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:

pip install altar altar-popfreq altar-clinvar

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:

cohort.tsv
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:

annotate.toml
[run]
job_id = "first-annotation"
genome_build = "hg38"

[variants]
path = "cohort.tsv"

[sources.gnomad]
type = "gnomad"

[sources.clinvar]
type = "clinvar"

Run it:

altar run annotate.toml

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:

pip install altar-legnet

Fetch UCSC's hg38 genome and the official WTC11 checkpoint:

altar resources fetch hg38
altar resources fetch legnet/wtc11

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:

score.toml
[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" and resources = "legnet/wtc11" name what altar resources fetch downloaded. 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:

altar run --validate score.toml

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:

altar run score.toml

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

altar run score.toml

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:

[models.legnet-wtc11.configuration]
average_reverse = false

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