Skip to content

Install Altar

Pre-release documentation

These pages describe Altar 0.4.0, which is not yet on PyPI. pip install altar installs 0.3.0, which lacks some commands shown here. To follow these pages now, install the development branch.

Install the altar package, the optional extras you need, and one binding for each model or annotation source you plan to use.

Before you start

  • Python 3.12 or newer. Platform support lists the operating systems and Python versions Altar runs on.
  • A virtual environment for Altar:

    python3 -m venv altar-env
    source altar-env/bin/activate
    

    If your system Python is older, uv can make one: uv venv --seed --python 3.12 altar-env. --seed puts pip in the environment.

  • Docker, only if you will score with a model that runs in a container. The support page lists the CPU architectures and GPUs the model images need.

Install the core package

pip install altar

This installs the altar command and the Python package. It includes:

  • reading VCF and TSV variants and checking them against a reference genome;
  • the local Docker execution backend;
  • SQLite storage for scores, detail tables and annotations;
  • the conformance test suites for extension authors.

It installs no model framework, no model weights and no cloud SDK. Those come with the extras, bindings and model images below.

pip install altar also installs altar-identity, the small package that defines variant IDs and file digests. Altar pins its exact version and re-exports its names, so you do not install or import it yourself. See the identity package.

The region annotations (coding, intronic, promoter and so on) read data files that the package does not include. Genomic regions says where to get them.

Add optional extras

Extras add cloud storage, warehouses and remote execution. Name them in brackets, and quote the argument in your shell:

pip install "altar[gcs,hf]"
Extra Adds
altar[gcs] Google Cloud Storage: gs:// datasets and stores, and altar pull --to gs://…
altar[hf] Hugging Face repositories: hf:// datasets and the hf mirror of published datasets
altar[s3] s3:// datasets and storage
altar[azure] Azure storage: az:// and abfs://
altar[http] http:// and https:// datasets
altar[fsspec] fsspec alone, for local and memory:// paths; each storage extra above includes it
altar[bigquery] BigQuery score and detail stores, BigQuery tables as sources, and altar pull --bigquery
altar[kubernetes] The Kubernetes execution backend
altar[modal] The Modal execution backend
altar[test] Altar's own test and type-checking tools
altar[docs] The tools that build this site

The support page says how each backend and store is tested.

Add bindings

A binding is a separate package that adds one model or one annotation source: a dataset a run looks variants up in, such as gnomAD. Each binding requires altar. Install the ones you need, for example:

pip install altar-popfreq altar-clinvar altar-legnet

altar and every binding share one version number. Upgrade them together.

Distribution Adds Install
altar-chrombpnet ChromBPNet model PyPI
altar-cherimoya Cherimoya model PyPI
altar-enformer Enformer model PyPI
altar-borzoi Borzoi model PyPI
altar-legnet LegNet model PyPI
altar-sei Sei model PyPI
altar-alphagenome AlphaGenome model, through Google DeepMind's hosted API PyPI
altar-popfreq gnomAD allele frequencies PyPI
altar-clinvar ClinVar classifications PyPI
altar-conservation phyloP 100-way conservation PyPI
altar-opentargets-e2g Open Targets E2G enhancer-to-gene links PyPI
altar-alphamissense AlphaMissense missense scores PyPI
altar-spliceai SpliceAI precomputed splice scores source checkout
altar-gpnstar GPN-Star precomputed scores source checkout
altar-e2g-atlas ENCODE-rE2G and scE2G enhancer-to-gene atlases source checkout

A model binding is small. The model itself runs in a container image that the first run pulls, or, for AlphaGenome, in Google DeepMind's service. Some annotation sources read a published copy of their dataset; others need you to build the dataset from the upstream release. Each binding's page says which, and what else it needs.

To annotate variants with no model, using the four annotation sources that read a published copy of their data:

pip install altar altar-popfreq altar-clinvar altar-opentargets-e2g altar-conservation

These read their published copies from a public bucket with no credentials.

Install from a source checkout

Install from a clone of the repository to use a binding that is not on PyPI, or to use changes that are not yet released.

Add a binding to a released Altar

To add a source-only binding to a released Altar, check out the tag of the version you have installed and install the binding's directory. pip show altar prints the installed version. For Altar 0.3.0 the tag is v0.3.0:

git clone https://github.com/kundajelab/altar.git
cd altar
git switch --detach v0.3.0        # the tag of your installed altar version
pip install -e bindings/spliceai

Install the development branch

To use the development branch, install Altar, altar-identity and the bindings from the same checkout with uv. altar pins the exact altar-identity version of its checkout, so install both from there:

git clone https://github.com/kundajelab/altar.git
cd altar
uv venv --python 3.12
uv pip install -e altar -e identity -e bindings/spliceai

uv sync --all-packages in the checkout installs Altar, altar-identity and every binding into .venv in one step. The tutorials use it.

To set up a checkout for working on Altar itself, see Development.

Check the result

altar models
altar sources

altar models lists the installed models and the type a run spec gives each one. altar sources lists the installed annotation sources. A binding you installed should appear in one of the two lists. To see the installed version of Altar:

import altar

print(altar.__version__)

If it fails

  • pip reports that no version satisfies altar: your Python is older than 3.12. Make an environment with a newer Python, as Before you start shows.
  • pip cannot build pysam on Windows: Altar does not run on Windows. See Platform support.
  • pip finds no altar-spliceai, altar-gpnstar or altar-e2g-atlas: these install from a source checkout.
  • A binding is missing from altar models or altar sources: it is installed in another environment. Activate the environment you installed Altar into, and install the binding there.
  • pip refuses a binding because of its altar requirement: the binding and altar are from different releases. Upgrade both to the same version.

Next

  • Quickstart: annotate a list of variants, then score them with LegNet on the CPU.
  • Tutorials: five notebooks that build one analysis, from published evidence to model scores.
  • Catalog: every model and annotation source, with what each needs.