Add interpretation to a model binding¶
An interpretable model binding explains its model's predictions for variants: it declares interpretation methods,
such as contribution scores, motif hits or plots, and builds the container workflow that writes each method's files.
altar interpret and altar.interpretation.interpret() then run it. Interpretation is Provisional: its hooks are
expected to change (see Provisional names).
When to add interpretation¶
Add it to a container model binding whose runtime can explain a prediction, not only score it. The files a method writes are stored as interpretation products, keyed by an interpretation ID, and never become scores; see Choose a result shape. Write the scoring binding first, as in Add a model binding.
The interface¶
Subclass InterpretableModel, imported from altar.interpretation, instead of ModelPlugin. It is a
ModelPlugin, so it keeps every scoring member, and adds these hooks:
| Hook | What it returns |
|---|---|
interpretation_methods() |
The InterpretationMethod values: each one's version, the targets it explains, its products as ArtifactSchema values, and at most one method it requires. |
interpretation_scientific_dict(configuration, method=, target=) |
{"configuration": ..., "parameters": ...}: the resources the method reads, by digest, and every constant the plan passes on its scientific command lines. |
interpretation_runtime_identities(configuration, method=) |
The image of each runtime the method's tasks run, by the manifest's runtime role. |
build_interpretation_workflow(request, selection=, variants_digest=) |
The plan for the requested chain of methods, with every product file as a terminal output. |
interpretation_rows(method=, product=, variants=) |
One InterpretationRow per row of a product file: the variant, its 0-based reference span, and the offset of its first base. |
interpretation_input_span(method=, variant=) |
Optional. The reference span the method reads, so preparation refuses a variant whose span runs off its contig. |
interpretation_variant_problem(method=, variant=) |
Optional. Why the runtime cannot interpret a variant, such as a contig it does not score, or None. |
interpretation_genome_index(run_inputs) |
Optional. The reference's declared .fai. Without one, preparation reads the index beside the FASTA. |
Requesting a method runs its whole chain, upstream method first. The ChromBPNet and Cherimoya bindings implement these hooks.
What decides an interpretation ID¶
Altar builds each method's interpretation ID from these hooks, the plugin, the method, its version, the target,
the upstream method's ID and the genome. Keep locations, file formats and settings that only scoring reads out of
configuration and parameters.
A setting only interpretation reads is a field of the model configuration, which [interpretations.<name>]
configuration sets. Record it in parameters, and leave it out of the configuration's scientific_dict(), so it
never changes a score lineage. ChromBPNet's reference_seed works this way. A setting added after a method's first
release keeps that release's IDs at its default when the default is left out of the saved configuration.
Before anything is staged, Altar refuses a workflow whose tasks run an image, or stage a digest, that no method of the chain records, other than the variant file. For a run with a genome, it also refuses a variant whose REF does not match the reference. Interpretation IDs are fixed from a method's first release, so pin them in a test.
Register the entry point¶
An interpretable binding registers like any model binding: in the altar.model_plugins group, under its
model_type. See step 6 of Add a model binding.
Test with the conformance suite¶
Subclass InterpretableModelContract from altar.testing, beside the binding's scoring suites. It takes five
fixtures:
plugin: the binding's plugin;interpretation_request: an interpretation request for a fully configured model;selection: the method and target whose chain covers every method;golden_ids: the pinned interpretation ID of each method of that chain;variants: canonical variants whose windows lie inside the reference.
The suite checks that the methods form chains, that each interpretation ID matches its pinned value, that no
location or format enters the identity, that an undeclared method or target is refused, that every product file is
a plan output, and that interpretation_rows() describes each variant in order.
Ready when¶
- Each
InterpretationMethoddeclares its version, targets and products, andrequiresat most one method. interpretation_scientific_dict()holds every resource digest and constant that changes a method's output, and nothing else.InterpretableModelContractpasses, with the interpretation IDs pinned.- The model's page documents each method, its products and its validation.
Next¶
- Interpret variants shows a run from the command line.
- Run and read interpretations shows how your own code runs and reads an interpretation.