Skip to content

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.

Models and annotation sources connect to Altar's shared contracts (variant identity, plans, result stores, provenance), which connect to execution backends and to stores and storage. Models and annotation sources connect to Altar's shared contracts (variant identity, plans, result stores, provenance), which connect to execution backends and to stores and storage.

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