Skip to content

Run and read interpretations

An interpretation explains a model's prediction for a variant: which bases drive it, what the model predicts at each base, and which motifs those bases form. altar.interpretation runs a binding's interpretation methods, stores every file they write, and returns each variant's files with the reference span every row covers.

Interpretation is provisional: every name in altar.interpretation, and the interpretation names in altar.run, are expected to change. Two models interpret: ChromBPNet and Cherimoya. Their methods, products and coordinates are on the ChromBPNet page and the Cherimoya page. To run interpretations from a spec with altar interpret, and to read their products, see Interpret variants.

A method is one interpretation step a binding declares, such as ChromBPNet's deepshap_counts or Cherimoya's ism_counts. Requesting a method runs it and every method it requires: ChromBPNet's finemo_hits runs deepshap_counts first. Three IDs name what ran:

  • An interpretation ID identifies one method run. It hashes the method and its version, the target it explains, the model resources it reads by digest, the runtime images, the genome, and the method's settings. It holds no path, run ID or resource location, and it is never a score lineage.
  • An operation is one request: the requested chain's interpretation IDs and the sorted input variants. The same request on the same model always has the same operation ID. A variant's stored products serve every later request that includes it.
  • An execution is one run of an operation's plan for the variants with no stored products, labelled by its run_id. Each method of an execution is committed as a unit, upstream first.

Run an interpretation

altar.interpretation.interpret runs one request on an execution backend, stores what it writes, and reads it back. This example runs deepshap_counts for two variants on local Docker. It needs a ChromBPNet resource manifest, written by altar-chrombpnet-resources, and the hg38 FASTA:

import asyncio
from dataclasses import replace

from altar.execution import LocalDockerExecutionBackend, LocalStorage
from altar.interpretation import InterpretationSelection, StorageInterpretationStore, interpret
from altar.models import InterpretationRequest, ResourceReference, sha256_file
from altar_chrombpnet import ChromBPNetConfiguration, ChromBPNetPlugin, ChromBPNetRunInputs


def staged(transfer):
    """Place the variant file under a staging directory; a model resource keeps its own location."""
    if transfer.uri != transfer.logical_path:
        return transfer
    return replace(transfer, uri=f"/data/staging/{transfer.logical_path}")


def collected(transfer):
    """Collect each product file under a results directory."""
    return replace(transfer, uri=f"/data/results/{transfer.logical_path}")


async def main() -> None:
    backend = LocalDockerExecutionBackend(data_root="/scratch/altar-volume")
    storage = LocalStorage()
    genome = ResourceReference(uri="/data/hg38.fa", digest=sha256_file("/data/hg38.fa"))
    with StorageInterpretationStore(storage, "/data/interpretations", "/data/interpretations/index.sqlite") as store:
        result = await interpret(
            ChromBPNetPlugin(),
            InterpretationRequest(
                run_id="interpret-0001",
                model_id="k562-dnase",
                configuration=ChromBPNetConfiguration.from_resource_manifest("chrombpnet.resources.json"),
                run_inputs=ChromBPNetRunInputs(genome_build="hg38", genome=genome),
                resolver=backend.path_resolver(),
            ),
            selection=InterpretationSelection(method="deepshap_counts", target="counts"),
            variant_ids=["chr6:136274285:A:G", "chr6:136274004:C:T"],
            model_name="K562 DNase",
            store=store,
            storage=storage,
            backend=backend,
            input_transfer=staged,
            output_transfer=collected,
            checkpoint_uri="/data/runs/interpret-0001.json",
        )
        for variant in result.interpretation.variants:
            for entry in variant.product("contribution_scores"):
                print(variant.variant_id, dict(entry.record.key.shard), await store.locate(entry.record), entry.row)


asyncio.run(main())

interpret prepares the operation, clears every location a product is collected to, runs the plan, and commits each method whose files are complete. When a stage fails, the files of every stage that finished are still collected, so a failed finemo_hits still commits deepshap_counts. It then raises InterpretationRunError, whose result holds what was stored.

entry.row is the variant's row in the file store.locate returns. entry.record names the product, its shard (such as allele=ref) and the reference span each row covers; the ChromBPNet page maps elements of a row to reference bases.

With checkpoint_uri, interpret records the execution's progress there, and calling it again with the same run_id resumes it. An execution stopped while its tasks ran runs again. One stopped after it collected its files stores them without running, if their digests still match. An execution that committed products never runs again; give the next one a new run_id.

Run a spec's interpretations

altar.run.interpret runs a spec's [interpretations.<name>] sections, as altar interpret does. It names each execution after its operation, records progress in the cache, [run] cache_dir, and moves to <run_id>-attempt2 after a failure. With read_only=True it runs nothing and reads what the sections stored:

import asyncio

import numpy as np
from altar.run import interpret


async def main() -> None:
    summary = await interpret("my-run.toml", read_only=True, read_variants=["chr6:136274285:A:G"])
    for product in summary.products:
        if product.product == "contribution_scores":
            scores = np.load(product.uri)[product.row]
            print(product.shard, product.chrom, product.start, scores[product.anchor])


asyncio.run(main())

Each InterpretationProduct gives the file's uri, the variant's row in it, and the 0-based, half-open reference span start to end that the row covers. anchor is the offset of the variant's first base in that span. Read the products describes every field.

Run the steps yourself

When your own code drives execution, call the steps one at a time: prepare, run, ingest, read. run_id labels one execution of the plan; choose a new one for each execution.

from altar.interpretation import (
    InterpretationSelection,
    ingest_interpretation_results,
    prepare_interpretation,
    read_interpretation,
)
from altar.models import run_model_workflow


async def interpret_step_by_step(plugin, request, *, store, storage, backend, staged, collected):
    preparation = await prepare_interpretation(
        plugin,
        request,
        selection=InterpretationSelection(method="finemo_hits", target="counts"),
        variant_ids=["chr1:1000000:A:G", "chr2:5000000:CAT:C"],
        model_name="K562 DNase",
        store=store,
        storage=storage,
        destination_transfer=staged,
    )
    if preparation.plan is not None:
        await run_model_workflow(preparation.plan, backend=backend, input_transfer=staged, output_transfer=collected)
        await ingest_interpretation_results(
            plugin, preparation, store=store, storage=storage, output_transfer=collected
        )
    return await read_interpretation(store, preparation.operation)

prepare_interpretation refuses a request before anything is staged when:

  • the method or target is not one the binding declares;
  • a variant ID is not canonical, or the model's manifest does not admit the variant;
  • the binding's runtime rejects the variant, for example because it is on a contig the runtime does not interpret;
  • a variant's contig is not in the reference index, or its window runs off the contig. The index is the one the binding names in the run inputs, or the .fai beside the FASTA;
  • a variant's REF is not the reference bases at its position. Preparation reads those bases from the FASTA through storage, so a remote reference is downloaded first.

It then records the operation and asks the store which variants have no committed product. The plan runs exactly those variants. With none missing, preparation.plan is None.

run_model_workflow(..., collect_completed=True) collects the files of every stage that finished before a stage failed, and the WorkflowExecutionError it raises names them; ingest them as usual.

ingest_interpretation_results commits one method at a time, upstream first. A method commits only when every file it declares was collected and its rows describe exactly the executed variants. A method downstream of one that did not commit is skipped, and the result's skipped says why.

read_interpretation returns one entry per product file that describes a variant. All of a variant's entries come from one execution, so motif hits always pair with the contributions they were called on.

To trace a product to its inputs, InterpretationStore.read_operation returns any operation by ID, with its descriptors and input variants, and InterpretationStore.describe returns an interpretation ID's descriptor: the model resources and genome by digest, the runtime images and the method's settings. InterpretationOperation.from_json rebuilds an operation from its JSON and checks every ID against what it hashes.

What reruns after a change or an interruption

Situation What happens
The same request again Same operation ID; nothing runs, and the same records are read.
More variants than last time Only the new variants run.
Another target, or another method New interpretation and operation IDs. The earlier records stay readable and never answer the new request.
Another motif set deepshap_counts keeps its ID and finemo_hits gets a new one. The chain reruns for every variant, and the new contributions are stored beside the earlier ones.
Another ChromBPNet reference_seed Both methods get new IDs, and the chain reruns for every variant. Scores keep their lineage.
A peak set, strand policy or resource location changes Nothing; none of them is part of an interpretation ID.
The driver stops while tasks run Nothing is stored. Run it again with the same run_id and the execution runs again.
The driver stops after collecting, before every method committed The committed methods stay. Run it again and the collected files are stored without running.
A downstream stage fails The upstream method commits and the downstream one does not. The next execution reruns the chain for those variants.

ChromBPNet's DeepSHAP method 2.0.0 uses 20 dinucleotide shuffles seeded by the configuration's reference_seed, 0 by default. Its descriptor records the seed, the shuffle count and the sha256-variant-allele-pcg64-v1 reference policy. Each variant and allele has its own random stream, shared across folds and independent of batching, ordering and retries. The interpretation image is separate from the scoring image, so changing the scoring image setting does not change interpretation IDs. A CPU replay is bitwise identical on the validated fixture; results on different devices need a tolerance.

Next