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:
If your system Python is older, uv can make one:
uv venv --seed --python 3.12 altar-env.--seedputspipin 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¶
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:
| 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:
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:
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 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:
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
pysamon Windows: Altar does not run on Windows. See Platform support. - pip finds no
altar-spliceai,altar-gpnstaroraltar-e2g-atlas: these install from a source checkout. - A binding is missing from
altar modelsoraltar 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
altarrequirement: the binding andaltarare 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.