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
.faibeside 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¶
- Interpret variants runs the same methods from a run spec with
altar interpret. - Serve annotations from your own tables joins your own evidence to the scores.
- Add interpretation to a model binding declares methods for another model.