Choose an interface¶
An extension is a separately installed package that adds one capability to Altar: a model, an annotation source, a place to run tasks, or a place to keep results. A package that adds a model or an annotation source is a binding; the class it registers is a plugin. Pick the interface to implement, and the shape of the results it produces, from the tables below. Each guide in this section then follows the same order: what to implement, a minimal working implementation, registering the entry point, testing with the conformance suite, and a "Ready when" checklist.
Select the figure to open it full size.
Pick the interface¶
Start from what your package does during an analysis.
| You are adding… | Implement | Import from | Status | Guide |
|---|---|---|---|---|
| a model that runs inference in a container | ModelPlugin |
altar.models |
Stable | Add a model binding |
| a model that runs inference by calling a hosted API, or in Python | ModelPlugin |
altar.models |
Stable | Add an inline model binding |
| precomputed per-variant evidence | AnnotationSource |
altar.sources |
Stable | Add an annotation source |
| per-variant evidence a SQL store reads inside its own query | SqlAnnotationSource |
altar.sources |
Stable | Add an annotation source |
| lookup of records by allele, from a file, database or warehouse | AllelicRecordBackend |
altar.sources |
Stable | Add an annotation source |
| one-to-many variant-to-gene evidence | VariantGeneLinkSource |
altar.sources |
Stable | Variant-to-gene links |
| persistent storage of normalized variant–gene evidence | VariantGeneLinkStore |
altar.sources |
Stable | Variant-to-gene links |
| a place to run container tasks | ExecutionBackend |
altar.execution |
Stable | Add an execution backend |
| file and object movement for a backend or a run | Storage |
altar.execution |
Stable | Validate an implementation |
| a database or warehouse for model scores | ScoreStore |
altar.results |
Stable | Add a result store |
| storage for a model's named detail tables | DetailStore |
altar.results |
Stable | Add a result store |
| storage for a model's artifact files | ArtifactStore |
altar.results |
Stable | Add a result store |
| a way of reaching object storage or a warehouse with its own credentials | Connection |
altar.connections |
Provisional | Add connections and published datasets |
| a copy of a source's data that its publisher hosts | AnnotationSource.published_dataset(), returning a PublishedDataset |
altar.sources |
Provisional | Add connections and published datasets |
| contribution scores, motifs or other files that explain a prediction | InterpretableModel |
altar.interpretation |
Provisional | Add interpretation to a model binding |
| token authentication | AuthProvider |
altar.access |
Provisional | Entry-point groups |
| asynchronous job handoff | JobQueue |
altar.execution |
Provisional | Entry-point groups |
Provisional names are importable, and their shape is expected to
change. Altar ships AuthProvider only as the development-only DevAuthProvider, and JobQueue only as the
InMemoryJobQueue test double.
Model or source?¶
Ask whether inference runs during the analysis:
- Yes: write a model binding. It declares how the work runs, and Altar stores the scores it produces.
- No, the values already exist: write an annotation source or a variant–gene link source, and record the data release in its identity.
Where a dataset came from does not decide its interface. Precomputed neural-network scores, such as a published SpliceAI or GPN-Star table, are an annotation source when the analysis only reads them, and Altar ships both as annotation sources in the catalog.
Choose a result shape¶
Altar keeps results apart by what produced them and how long they are kept. Pick the shape by meaning, not by how many rows a variant gets. A score lineage is the set of scores one computation produced: one model with one set of weights and settings, one plugin version and one runtime image.
| Result | Declare it with | Stored by | Belongs to |
|---|---|---|---|
| one row of scalar scores per variant and model | ResultSchema in the manifest |
ScoreStore |
the model instance and its score lineage |
| repeated rows per variant from one model run, such as one per track, gene or splice event | DetailSchema in the manifest |
DetailStore |
the run that produced them, under the primary rows' lineage |
| files Altar never decodes, such as a prediction matrix or a predicted profile | ArtifactSchema in the manifest |
ArtifactStore |
the task that wrote them, under the primary rows' lineage |
| precomputed evidence looked up per variant | AnnotationContract and AnnotationSource |
the source's own data | a data release |
| reusable variant-to-gene relations | VariantGeneEvidenceRecord and VariantGeneLinkSource |
VariantGeneLinkStore |
a normalized evidence release |
| files that explain a prediction (provisional) | InterpretationMethod products, each an ArtifactSchema |
InterpretationStore |
the interpretation ID of the method run, never a score lineage |
A five-row-per-variant splice prediction and a ten-thousand-track prediction are both details when an Altar run produced them. A precomputed SpliceAI table stays an annotation source even when one lookup returns several gene records. A model's detail rows become variant–gene links only through an explicit normalization step that writes records with the link contract's provenance.
The primary score table has one scalar row per model and variant. It is the table that filtering, prioritization
and cross-model export read. A binding may reduce its detail rows into headline primary fields, such as the
largest effect and the track it came from. Each of those fields declares its own meaning in the ResultSchema,
and the detail table keeps every observation. Altar does not assume a detail table has a meaningful reduction.
An artifact is produced only when a run's output selection names it, so declaring one changes no existing run's identity. Use an artifact for a matrix too large for rows. Never encode a matrix as thousands of scalar columns.
Some examples:
- A splicing model run live: a scalar maximum in the primary table, and variant × gene × splice-event rows in a detail table.
- AlphaGenome: headline reductions in the primary table, and a per-track detail table.
- Sei: chromatin-profile effects as an opt-in artifact.
- ENCODE-rE2G and scE2G atlas records: variant–gene links in a link store.
Keep bindings and infrastructure separate¶
A binding produces plans or evidence that name no compute system or database. An execution backend, a store or a connection reads only the public interface for its role. Each new model then runs on every backend, and each new store holds every model's scores.
Don't write a package for one model on one backend, or one dataset in one database. A Cherimoya binding runs
on local Docker, Kubernetes and Modal through the same plan. An E2G importer writes VariantGeneEvidenceRecord
values into any VariantGeneLinkStore. It does not become a Postgres source, a Parquet source and a SQLite source
that each repeat the scientific normalization.
When an extension counts as supported¶
An implementation is ready to depend on when it has:
- a real consumer: a run spec, a binding or an application that uses it;
- complete schemas and identity, so stored results can be told apart;
- defined behavior for missing data and for errors;
- an entry point in the matching
altar.*group (see Package and register a plugin); - the matching conformance suite from
altar.testing, passing (see Validate an implementation); - documentation of its science and its operation;
- dependencies only on Altar's public modules and on public third-party packages.
A new interface in Altar itself meets the same bar before it is labelled Stable. Until then it is Provisional.
Next¶
- Add a model binding or Add an annotation source, for the two most common extensions.
- Package and register a plugin covers the entry points every extension declares, and a model's manifest and versioning.