Score variants with a model¶
A [models.<name>] section adds a model's predicted effect of each variant to the run's table, and a store keeps
the scores so a later run reuses them. The examples start from the quickstart's LegNet run.
Before you start¶
- Start 2 of the quickstart: its
score.toml,hg38.faandlegnet-resources, and Docker on an x86-64 (amd64) machine. Every model except AlphaGenome runs in a container built forlinux/amd64. - For a GPU model (ChromBPNet, Cherimoya, Enformer, Borzoi, Sei): an NVIDIA GPU and the NVIDIA Container Toolkit. Their images are 2.8 to 6.1 GB compressed. Run tasks on a GPU or a cluster covers the backend.
- For AlphaGenome: an API key, and no Docker.
Platform support lists what is tested.
Find a model¶
altar models lists the models you have installed, grouped by the binding that ships each one (abbreviated):
$ altar models
Models score your variants. To use one, put its type in a run spec:
[models.alphagenome]
type = "ALPHAGENOME"
Run `altar models <name>` to see a model's configuration, inputs and outputs.
altar-alphagenome
ALPHAGENOME
Predicts how a variant changes the tracks you select, such as ATAC, DNase or RNA-seq, through
a hosted API.
type = "ALPHAGENOME"; inline; hg38, mm10; every variant class; 6 columns
...
altar-legnet
LEGNET
Predicts how a variant changes MPRA regulatory activity in a human cell type.
type = "LEGNET"; container; hg38; SNVs only; 3 columns
...
Install a model's binding to list it, such as pip install altar-legnet. The catalog
lists every model with its binding.
altar models <type> shows one model in full: a section to paste, every configuration field with its default, the
builds and variants it accepts, its columns, detail tables and artifacts, its image and the compute it asks for:
$ altar models legnet
LEGNET (altar-legnet)
Predicts how a variant changes MPRA regulatory activity in a human cell type.
Plugin org.kundajelab.altar.model.legnet 0.0.1
Add it to a run spec:
[models.legnet]
type = "LEGNET"
resource_manifest = "legnet.resources.json"
[models.legnet.configuration]
# cell_type = "..." # required, text, unless the resource manifest gives it
Configuration, under [models.legnet.configuration]:
A resource manifest can give the resource fields instead: name its path as resource_manifest in
[models.legnet].
weights required, resource
training_config required, resource
cell_type required, text
assay text, default "LentiMPRA"
average_reverse true or false, default true
image text, default
"riyavsinha/altar-legnet@sha256:43a4000583f5ebda33554a21a6b627f071a43a65da76c77c625eb1c4f3d50d0d"
Inputs:
Genome builds: hg38
Variants: SNVs only; batch preparation sets the others aside and reports them
Columns it adds (result schema 0.0.1):
ref_activity float Reference Activity
alt_activity float Alternate Activity
activity_delta float Activity Delta
Runtime:
Runs in a container on the spec's [backend].
Default image, pinned by digest:
riyavsinha/altar-legnet@sha256:43a4000583f5ebda33554a21a6b627f071a43a65da76c77c625eb1c4f3d50d0d
Compute: CPU only, up to 4 GB of memory per task
Documentation: https://kundajelab.github.io/altar/integrations/legnet/
The command reads what each binding declares. It loads no weights and pulls no image. --json prints the same
information as JSON.
Configure it¶
A model reads its weights from files you fetch once. altar resources fetch legnet/wtc11 downloads LegNet's and
checks their digests, as in the quickstart; see Find and fetch models and genomes. Other models'
bindings have their own resource command, and each model's page names it.
The quickstart's score.toml holds one model section:
- The model key,
legnet-wtc11, names the model's scores in the store. Keep it the same across runs: a later run reuses stored scores only under the same model key. resourcesnames a registry entry,legnet/wtc11, which gives the model's type and its configuration: the weights and their digests, and every other field. A field in[models.legnet-wtc11.configuration]changes the entry's, such asaverage_reverse = false. A model whose binding has its own resource command names the manifest it wrote withresource_manifestinstead, besidetype.
A spec with a model keeps its scores in the cache, .altar/scores.sqlite, unless a [store] names another
place; see Choose where results are stored. A later run started from the same directory reuses them,
whatever its job_id. A container model needs a [backend];
Run tasks on a GPU or a cluster covers the backends. The
run spec reference lists every key of a model section, including run_inputs
and max_variants_per_batch. Each model's page in the catalog has a section to start
from.
altar run --validate score.toml (Provisional) parses the
model's configuration, builds the backend, checks data_root, and looks the image up with Docker, without reading
a variant. The quickstart shows its output.
A model that reads files a preparation step writes, such as ChromBPNet, needs altar prepare (Provisional) first;
see Prepare model resources.
Run it¶
For each model, altar run score.toml prints a line that says what the model did with the cohort. The first
run's line for LegNet, from the quickstart:
[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 34s
The first run also pulls the model's image. The line's counts:
5 candidates: the variants the run read.1 set aside: variants the model does not score, by reason, and the file that lists them. LegNet scores SNVs only, so it sets the ΔF508 deletion aside. The deletion stays in the export with its gnomAD and ClinVar columns, and its LegNet columns are empty.0 already scored: variants the store already held.4 scored in 1 batch: variants sent to the model. A batch holds up to 10,000 variants by default.
Copy the digest the run printed into [variants] reference_digest to skip hashing the genome next time; see
Pin the reference by its digest.
Run it again¶
A second run of the same spec counts 4 already scored and starts no container. A variant counts as already
scored when the store holds its row for the model key and settings, and its detail rows and selected artifacts
when the model has them. Add variants to the cohort and the next run sends only the new ones to the model.
Score reuse and provenance describes when a stored score is
reused.
Change a setting and rerun¶
A setting that changes a score starts a new set of scores, a lineage, under the same model key. The quickstart's
Change a setting turns off LegNet's average_reverse: the next run scores
the SNVs again and keeps the new scores beside the old ones. The export always holds the scores of the settings
in the spec, and its score_lineage_id column names the lineage they came from.
A setting that does not change a score, such as where the weights are stored or the batch size, starts no new lineage.
A new SQLite store keeps lineages. A store file created without them holds one set of settings per model key, so a changed setting stops the run:
altar run: error: [models.legnet-wtc11]: stored scores for model 'legnet-wtc11' use incompatible scientific scoring semantics. The store at scores.sqlite keeps no lineages, so it holds one setting per model key. Give the changed model a new key, such as [models.legnet-wtc11-2], or keep scores in a new store with lineages = true, such as [store] options = { path = "scores-lineages.sqlite", lineages = true }
Follow either suggestion. A store file keeps the mode it was created with; the run does not convert it.
Select details and artifacts¶
The export holds each model's primary columns, one row per variant. Some models write more:
- A detail table has many rows per variant, such as Enformer's
track_effects, one per selected track, or Sei'ssequence_class_effects, one per class. A model writes its detail tables on every run. The run keeps them in the detail store, which is beside the score store unless[detail_store]names another. - An artifact is a file the run stores without reading it, such as Sei's
chromatin_profile_effectsmatrix. A model writes one only when itsoutputselects it, and the spec then needs an[artifact_store].
altar models <type> lists a model's detail tables and artifacts. This section selects Sei's artifact:
[models.sei]
type = "SEI"
[models.sei.configuration]
# The five resources, with the digests the Sei page gives: weights, projection_vectors,
# histone_indices, sequence_class_names and target_names, which the artifact needs.
[models.sei.output]
outputs = ["scores", "sequence_class_effects", "chromatin_profile_effects"]
reducer = "official_nucleosome_adjusted_sequence_class_effect_v1"
[artifact_store]
type = "storage"
The Sei page gives the four score resources with their digests,
and its artifact section adds target_names. The
storage artifact store keeps the files under <cache_dir>/artifacts; Store
artifacts puts them elsewhere. A different output selection is a
different lineage, so selecting the artifact scores the cohort again. The run summary's details and artifacts
list what each model added. Read details and artifacts reads them back.
Give a hosted model its credentials¶
AlphaGenome runs in the altar process and calls Google DeepMind's hosted API.
It needs no [backend] and no reference FASTA. It reads its API key from an environment variable that the spec
names, so the key never enters the spec:
[models.alphagenome]
type = "ALPHAGENOME"
[models.alphagenome.configuration]
credential = { provider = "env", name = "ALPHAGENOME_API_KEY" }
ontology_terms = ["UBERON:0002107"] # liver; narrow the tracks to your tissues
scorers = ["ATAC"]
Export the variable, then run:
provider = "env" is the only provider altar run reads. When the variable is unset, the run and
altar run --validate stop before reading any variant and name it:
altar run: error: [models.alphagenome] configuration.credential: the environment variable ALPHAGENOME_API_KEY is not set; export it before running
The key's value never enters the run summary or a stored identity. Each variant is one API call, which counts against your API quota. To pass a resolver of your own from Python, see Use Altar from Python.
Check the result¶
Each model adds its columns under a prefix of its model key and a short hash, such as
legnet_wtc11__60a71072bf29_activity_delta. The quickstart reads them. A
variant the model set aside has empty columns for that model.
Each model also adds its own prioritized column; read What "prioritized" means
before you use it. Read a run's results describes the rest of the export and how to tell two runs'
exports apart.
If it fails¶
- A container model in a spec with no
[backend]stops the run, and the message says to add[backend]withtype = "local". - An
imagethat is not pinned by digest, asname@sha256:<64 hex digits>, is refused; a tag such as:latestis not accepted.
Fix a run that stops or warns covers configuration errors, a missing reference and the other messages.
Next¶
- Run tasks on a GPU or a cluster runs GPU models, and Kubernetes and Modal backends.
- Choose where results are stored keeps scores in a SQLite file or BigQuery, and artifacts in a bucket.
- Prepare model resources runs a model's preparation step before scoring.
- Read a run's results reads scores, details, artifacts and provenance.
- Tutorial 1: score variants locally with Cherimoya scores five variants in a notebook, step by step.