Skip to content

Store and assemble results

A model run writes three kinds of result, each to its own store:

Store Holds Implementations (registry name)
ScoreStore One row per variant and model: the model's primary score columns. SqliteScoreStore (sqlite), BigQueryScoreStore (bigquery)
DetailStore A model's named detail tables, with many rows per variant, such as one per track or gene. SqliteDetailStore (sqlite), BigQueryDetailStore (bigquery)
ArtifactStore Files the engine stores without reading them, such as a prediction matrix. StorageArtifactStore (storage)

The score store also assembles results: it joins each variant's scores with its annotations, decides prioritized, and exports the result. All of these are in altar.results and are stable. The BigQuery stores run on a Preview backend; Run at warehouse scale on BigQuery says how they are tested and covers their warehouse-only methods.

The scoring engine writes to these stores for you; see Score a cohort. Use the calls below to read them back, or to write to them yourself. Every store has close() and works as a with block. A store closes only what it opened: a client passed to its constructor stays open.

Declare the schema

Each model binding returns its primary columns as a list of ScoreColumn values, plugin.score_columns(). Before rows are written, ensure_schema(columns) adds the columns a store lacks. It never drops a column.

Two models may share a column name when the whole definition agrees. ChromBPNet and Cherimoya both write logfc, with the same meaning. A column of the same name with another definition raises SchemaCollisionError.

Write scores

The engine writes scores through ScoreStore.primary_write. To import scores computed elsewhere, call add_scores:

async def import_scores(store, plugin, plan, rows):
    # rows: one mapping per variant, with variant_id and the binding's score columns.
    result = await store.add_scores(
        model_id="k562-cbp",
        model_name="ChromBPNet K562",
        plugin_identity=plan.plugin_identity,
        rows=rows,
        columns=plugin.score_columns(),
    )
    print(result.added, result.skipped)

Each row keeps its model_id, model_name and the run's plugin_identity. The identity records the result schema, reducer, runtime, model configuration, output selection and genome build. A store refuses a model_id whose stored identity describes another model instance.

A score is a finite number or None. A store raises ValueError for NaN or an infinity before it writes any row of the call.

add_scores is not idempotent on every store:

  • SqliteScoreStore skips a row it already holds and counts it in skipped.
  • BigQueryScoreStore appends every row, so a repeated row is stored twice and reads pick one of the copies.

Ask the store which variants it lacks before scoring. Use prepare_scoring_batches for a cohort, or get_missing_scores(variant_ids, model_id, plugin_identity=..., columns=...) for a list. get_unscored_variants works only on a store without lineages.

A store created with lineages keeps several scoring versions of one model ID apart, and accepts older ones only when you ask. altar run creates new SQLite stores with lineages. See Reuse scores across model updates for lineages, reuse policies and registering imported scores.

Read details and artifacts

A detail table holds a model's repeated output, such as AlphaGenome's track_scores, one row per track. The binding declares each table as a DetailSchema with a name, a version, its fields and its key fields. Rows keep their parent variant_id, the model instance, and the lineage of the run that wrote them.

An artifact is a file, such as Sei's chromatin_profile_effects matrix. A model writes one only when the request's output selection names it. The store indexes which run produced each file and which variants it covers.

import asyncio

from altar.execution import LocalStorage
from altar.results import SqliteDetailStore, StorageArtifactStore


async def main() -> None:
    with SqliteDetailStore("details.sqlite") as details:
        async for row in details.read_rows(model_id="alphagenome-liver", detail_name="track_scores"):
            print(row["variant_id"], row["track_name"], row["raw_score"])
    with StorageArtifactStore(LocalStorage(), "artifacts", "artifacts/index.sqlite") as artifacts:
        async for record in artifacts.read_records("sei", "chromatin_profile_effects"):
            print(len(record.variant_ids), "variants in", await artifacts.locate(record))


asyncio.run(main())

Without accepted_lineage_ids, both reads return every lineage the store holds for the model. With a list of lineage IDs, a variant's rows come from the first lineage in the list that holds rows for it, so two producers' rows never mix. Pass variant_ids= to read only some variants.

BigQueryDetailStore(client, "project.dataset.detail_rows") keeps every table's rows as canonical JSON behind fixed key columns, so a new detail table needs no schema change. Its writes merge on the table's key, so writing a row again adds nothing.

Assemble variant results

To assemble each variant's scores and annotations into one result, call the score store's materialize. It yields one MaterializedVariant per requested variant. Each result holds the variant's model_scores, its annotations, and the prioritized decision with the models and sources that made it. Each model is a ScoredModel: its ID and name, its binding, and the run identity whose scores to read. The scoring calls return that identity, as preparation.plugin_identity or result.plugin_identity.

This function continues the cohort example. Call it inside that example's with block, after the batches have run, as await assemble(scores, plugin, preparation):

from altar.results import ScoredModel, ScoreReusePolicy


async def assemble(scores, plugin, preparation):
    model = ScoredModel(
        "alphagenome-liver",
        "AlphaGenome liver",
        plugin,
        preparation.plugin_identity,
        reuse_policy=ScoreReusePolicy.exactly(preparation.resolution.lineage_ids),
    )
    async for result in scores.materialize(
        variant_ids=["chr7:140753336:A:T", "chr1:1000000:A:G", "chr2:5:C:T"],
        models=[model],
        annotation_sources=[],
    ):
        print(result.variant_id, result.prioritized, [score["max_abs_quantile_score"] for score in result.model_scores])
    return model
chr1:1000000:A:G True [0.95]
chr2:5:C:T False []
chr7:140753336:A:T True [0.95]

The reuse policy reads the lineages preparation checked the cache against. Pass annotation_sources to join evidence; the sources' columns arrive in result.annotations.

Assembly first checks that the sources supply every column the models' rules read (annotation dependencies). It then reads each model's scores, evaluates the rules, and yields one result at a time, so a large job never holds the whole result in memory.

Every store yields the same results in the same order:

  • one result per distinct requested variant, so a repeated ID appears once;
  • in ascending variant_id order, compared as plain strings, so chr10:… sorts before chr2:…;
  • a variant no model scored still appears, with empty model_scores. It is prioritized only when a source's rule matches it.

result.annotations maps the declared annotation columns to the variant's values, merged across every source:

  • A column with no value is absent, never None. A source with no row for the variant, a null cell, and an empty repeated value all count as no value. A variant no source annotated gets {}.
  • Values keep their logical type. A repeated column is a list and a struct column is a dict, or a list of dicts when repeated. SQLite stores those columns as JSON text and decodes them on read. On BigQuery a repeated or struct column must be an ARRAY or STRUCT. A scalar json column may be a JSON value or JSON text, such as a relation= that projects TO_JSON_STRING(...); the text is decoded, and '[]' is absent like [].
region = result.annotations.get("region_type")  # None when no source has a value for this variant

BigQueryScoreStore.materialize joins the sources it can into one query and reads the others through annotate(); see Fused sources.

Export results

Every score store hands its results to the export writers the same way. result_buckets yields the job's variants in genomic order, a bucket at a time: each variant once, with its annotations and its models' scores nested. The writers render the buckets into any storage, so every store writes the same files:

Writer Writes
render_wide_tsv The wide table, gzipped and tab-separated, with a header. prioritized_only=True keeps the prioritized rows.
render_wide_parquet The wide table in Parquet.
render_prioritized_ndjson The prioritized variants as gzipped NDJSON, model_scores nested in the order of the models, for a database load. An integer is a string, a missing list is [], a null field is null, and NaN or infinity is "NaN", "Infinity" or "-Infinity".
render_long_export The long tables described below.
render_occurrence_buckets The buckets of an augmented VCF.
from altar.execution import LocalStorage
from altar.results import render_wide_tsv, write_column_manifest


async def export_all(scores, models, sources, variant_ids):
    async with scores.result_buckets(variant_ids=variant_ids, models=models, annotation_sources=sources) as buckets:
        await render_wide_tsv(buckets, "results/all", storage=LocalStorage())
        await render_wide_tsv(buckets, "results/kept", storage=LocalStorage(), prioritized_only=True)
        await write_column_manifest(buckets.layout, "results/all", storage=LocalStorage())

Rows come in genomic order: chromosomes 1, 2, … 22 (or 19 for mouse), X, Y and M by position, then any other contig. rider= adds display columns such as the most active cell type, computed by the store (Run at warehouse scale on BigQuery). A writer holds one bucket in memory; bucket_rows= or bucket_bytes= (default 128 MiB) sets its size. altar run writes its export this way. These names are provisional.

The store methods below write the same columns from materialize, in variant_id order:

Method Writes
export_download Every requested variant as one wide row: a gzipped, tab-separated file with a header. prioritized_only=True keeps the prioritized rows.
export_prioritized The prioritized variants as gzipped NDJSON, one MaterializedVariant per line with model_scores nested.
async def export_all(scores, model):
    return await scores.export_download(
        variant_ids=["chr7:140753336:A:T", "chr1:1000000:A:G"],
        models=[model],
        annotation_sources=[],
        destination_uri="results/all",
    )

The SQLite store writes one part, results/all/part-000000000000.csv.gz, through a storage= you pass, the local filesystem by default. BigQueryScoreStore writes part-*.csv.gz files under a gs:// prefix with one EXPORT DATA job. Both files are tab-separated despite the .csv.gz name. altar run writes the same wide table, as Parquet by default.

The wide table starts with variant_id and prioritized. The annotation columns follow, then each model's score columns and its own prioritized. A model's columns start with its name and a short hash of its ID, such as AlphaGenome_liver__232e7daec403_max_abs_quantile_score. A store with lineages adds each model's score_lineage_id. The last two columns say why a row was kept:

  • prioritized_model_ids lists the models whose rule returned true for the variant.
  • prioritized_source_names lists the annotation sources whose rule returned true.

Both follow the order the models and sources were passed in. A variant nothing kept has two empty lists. The TSV writes each list as JSON text; Parquet keeps a list of strings. Here is such an export with the model columns left out:

variant_id          prioritized  am_class           …  prioritized_model_ids  prioritized_source_names
chr12:5000123:C:T   true         likely_pathogenic  …  []                     ["alphamissense"]
chr12:5000456:G:A   true         likely_pathogenic  …  ["hepg2"]              ["alphamissense"]
chr1:1000000:A:G    true                            …  ["k562","hepg2"]       []

AlphaMissense alone kept the first row, the hepg2 model and AlphaMissense kept the second, and both models kept the third. Every store writes the same columns with the same values. See What prioritized means.

A tab-separated file cannot hold nested values. The TSV export writes each annotation column declared repeated or struct, such as am_transcript_scores, as JSON text, and leaves a missing value empty. A scalar json column is written unchanged. A float is its shortest text that reads back as the same number, and NaN or infinity is the cell NaN, Infinity or -Infinity, never an empty cell. The NDJSON and Parquet exports keep native types.

These files are Altar's own format, the same bytes from every store. BigQuery's own EXPORT DATA, behind BigQueryScoreStore.export_download and export_prioritized, holds the same values in other text: it writes floats to 15 or 17 significant digits, nan/inf/-inf in CSV, and leaves null fields out of JSON. To check one against the other, compare by value with altar.testing.compare_wide_tsvs(..., semantic=True) and altar.testing.compare_prioritized_ndjson. The declared AnnotationColumn decides the encoding, not the column's name.

List a wide table's columns

wide_layout(models, annotation_sources) returns the wide table's columns, and wide_column_manifest(layout) describes each of them: its kind, its field such as logfc, its type, and for a model's column the model key, binding, binding release and result schema. altar run writes the same list beside its export as _columns.tsv (Find a model's columns). For a table you write yourself, write the list beside it:

from altar.execution import LocalStorage
from altar.results import wide_column_manifest, wide_layout, write_column_manifest


async def describe(models, sources):
    layout = wide_layout(models, sources)
    for entry in wide_column_manifest(layout):
        if entry.kind == "score":
            print(entry.column, entry.model_id, entry.field)
    await write_column_manifest(layout, "results/all", storage=LocalStorage())

For a BigQuery export_download, pass the layout of the columns download_header returns: its display rider's column names as rider_columns, and score_lineages=True on a store with a lineage_table_id. column_manifest_tsv(entries) returns the file's text, to upload another way. These names are provisional.

Write the long tables

write_long_export(results, layout, destination_uri, storage=...) writes the materialize rows as the long format of Long format for many models: a models table, a variants table and one table per binding and result schema version, with a row per variant and model. It reads the rows once and holds one row group per table. export_format="tsv" writes gzipped TSV, and model_info adds each model's requested lineage and registry entry, as LongModelInfo, to the models table. It returns each table's directory:

from altar.execution import LocalStorage
from altar.results import long_score_tables, wide_layout, write_long_export


async def export_long(scores, models, sources, variant_ids):
    layout = wide_layout(models, sources)
    print([table.path for table in long_score_tables(layout)])  # ['scores/chrombpnet_v0_0_1__6b809b253c84']
    rows = scores.materialize(variant_ids=variant_ids, models=models, annotation_sources=sources)
    return await write_long_export(rows, layout, "results/long", storage=LocalStorage())

These names are provisional.

Choose a SQLite or BigQuery store

SqliteScoreStore(path, lineages=True) and SqliteDetailStore(path) are the local implementations. Each keeps one file, or ":memory:". The score store reads scores and assembles results in Python.

BigQueryScoreStore(client, "project.dataset.variant_scores", lineage_table_id=...) keeps one clustered table. It is Preview. It joins sources and evaluates prioritization rules in SQL, and its primary write unit is atomic: a failed ingest commits no row. BigQueryScoreStore.connect(table_id) builds its own client from ambient credentials and closes it on close(); it needs the altar[bigquery] extra.

Every implementation passes the same conformance suite, so code that uses only these methods works with any of them. Physical column types and write behavior differ. To write another store, see Add a result store.

Next