Skip to content

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.fa and legnet-resources, and Docker on an x86-64 (amd64) machine. Every model except AlphaGenome runs in a container built for linux/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:

[models.legnet-wtc11]
resources = "legnet/wtc11"
  • 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.
  • resources names 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 as average_reverse = false. A model whose binding has its own resource command names the manifest it wrote with resource_manifest instead, beside type.

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's sequence_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_effects matrix. A model writes one only when its output selects 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:

export ALPHAGENOME_API_KEY=...
altar run alphagenome.toml

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] with type = "local".
  • An image that is not pinned by digest, as name@sha256:<64 hex digits>, is refused; a tag such as :latest is not accepted.

Fix a run that stops or warns covers configuration errors, a missing reference and the other messages.

Next