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:
SqliteScoreStoreskips a row it already holds and counts it inskipped.BigQueryScoreStoreappends 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
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_idorder, compared as plain strings, sochr10:…sorts beforechr2:…; - 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
ARRAYorSTRUCT. A scalarjsoncolumn may be aJSONvalue or JSON text, such as arelation=that projectsTO_JSON_STRING(...); the text is decoded, and'[]'is absent like[].
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_idslists the models whose rule returned true for the variant.prioritized_source_nameslists 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¶
- Reuse scores across model updates accepts older scores of the same model.
- Run at warehouse scale on BigQuery keeps scoring, annotation and export inside BigQuery.
- Tutorial 3: put model scores beside evidence assembles stored scores with annotation sources in a notebook.