Reuse scores across model updates¶
A ScoreReusePolicy lets an analysis reuse older scores of the same registered model that you accept by name. For
example, a publisher may approve results from a previous model release, or an application may keep a historical scoring
method while it adopts a new one. Altar never treats two computations as equal because their version numbers are close.
Score reuse and provenance explains when a run reuses a score and what a lineage is.
The names on this page come from altar.results and are stable. The snippets run inside an async function. store
is the score store, plugin the model binding, plan its scoring plan and request the scoring request, as in
Score a cohort. The BigQuery store is Preview; see
Run at warehouse scale on BigQuery.
A stored score is keyed by four values: model_id, the input genome, the canonical variant_id, and
score_lineage_id. A model's training species is independent of the input genome. One imported lineage can describe a
scoring method shared by many models and genomes, and the other three keys still tell their rows apart. Keeping each
model ID tied to one trained model is up to you.
Create a store that keeps lineages¶
from altar.results import BigQueryScoreStore, ScoreLineage, ScoreReusePolicy
store = BigQueryScoreStore(
client,
"project.dataset.variant_scores",
lineage_table_id="project.dataset.score_lineages",
)
await store.ensure_schema(plugin.score_columns())
The score table holds one extra string column, score_lineage_id. The lineage catalog, the table lineage_table_id
names, records each lineage's metadata once, including the exact run metadata of a computation Altar ran. A provenance
table beside it, {lineage_table_id}__provenance, records each distinct exact run identity that wrote scores under a
lineage (see Read which runs wrote a lineage). A row carries no
plugin_identity_json of its own. A store built without lineage_table_id keeps one compatible identity per model ID
instead. Lineage tables lists the BigQuery tables and which ones you create.
For a new local store, use SqliteScoreStore(path, lineages=True). It keeps the catalog in _altar_score_lineages
and the provenance in _altar_score_lineage_provenance. A SQLite file created without lineages keeps another primary
key. It needs a schema migration before it can keep lineages, and Altar does not rebuild it.
Register existing scores¶
historical = ScoreLineage(
lineage_id="release-2025",
plugin_id=plugin.manifest.plugin_id,
columns=tuple(plugin.score_columns()), # declare the outputs actually present
metadata_json='{"description":"Publisher-approved historical scoring method"}',
)
await store.register_score_lineage(historical)
The catalog's JSON metadata holds anything else you record: model settings, release labels, provenance or notes. Imported scores need no Altar run identity. Registration cannot be changed, and registering the same declaration again does nothing. To change a declaration, register a new ID.
Then tag your existing rows with that ID. When every historical row comes from the declared method, the table's owner runs:
UPDATE `project.dataset.variant_scores`
SET score_lineage_id = 'release-2025'
WHERE score_lineage_id IS NULL;
Narrow the WHERE clause if the table holds rows from several scoring methods. ensure_schema only adds the nullable
column to an existing BigQuery table; it never runs this update. The update can scan a large table, so plan its cost.
It changes metadata, not score values, and the scores stay in their table.
A row whose lineage ID is NULL or not accepted is a cache miss.
What decides a generated lineage¶
A lineage ID that Altar computes is a hash of the run's scientific identity, PluginRunIdentity.scientific_dict(): the
plugin release, its exact runtimes, the score-changing configuration, the output selection, the genome build and genome
hash, and the primary result schema. A store accepts a run under an existing generated lineage when the plugin, the
declared output columns and that scientific identity agree, even if the run's exact identity differs. These runs
therefore reuse each other's scores and write under the same lineage:
- content-addressed resources served from a new location (same digest, different URI);
- a configuration-schema migration, or a setting that does not change scores, such as ChromBPNet's
peaks_compression; either changes only the exactconfiguration_hash; - a later Altar release, which changes
altar_api_versionor the plugin'ssupported_altar_api.
A different score-changing configuration, plugin release or runtime image is a different lineage and a cache miss. A
republished runtime image is a new computation. Its predecessor's scores are reused only when the binding declares the
two equivalent (see Equivalent lineages) or you accept the predecessor with a
ScoreReusePolicy.
An imported lineage, one with no run_identity, matches only an identical declaration. A generated ID can never be
rebound to an imported declaration.
Read which runs wrote a lineage¶
A score row is attributed to its lineage, not to the exact run that wrote it. The catalog's run_identity is one
deterministic representative of the lineage, usually the first run to register it. In BigQuery, concurrent first
registrations keep the smallest declaration, and a process that registered its own declaration may keep using it until
it restarts. StoredScore.lineage and an assembled result's plugin_identities carry that representative.
Every run that registers to write under a lineage also records its exact identity once, keyed by its hash, in the
provenance table, even when all its rows were skipped as duplicates. Read-only lookups such as get_missing_scores
record nothing. Read the exact identities, oldest first:
lineage_id = ScoreLineage.from_run(plan.plugin_identity, plugin.score_columns()).lineage_id
exact_runs = await store.read_lineage_provenance(lineage_id) # tuple[PluginRunIdentity, ...]
The result always includes the catalog's representative, even when the provenance table has no row for the lineage. An imported lineage, or an ID the store never registered, returns an empty tuple.
Accept older scores¶
reuse = ScoreReusePolicy(accepted_lineage_ids=("release-2025",))
missing = await store.get_missing_scores(
candidate_ids,
model_id,
plugin_identity=plan.plugin_identity,
columns=plugin.score_columns(),
reuse_policy=reuse,
)
The current run's lineage is always accepted and preferred. The other accepted IDs are tried in the order you list them. Acceptance applies to that one request, names each lineage explicitly, and does not carry over: accepting B, which once accepted A, does not accept A. On a store that keeps lineages, an empty policy accepts only the current run.
To let a future run reuse the current run's scores, list the current run's generated ID in the future run's policy:
ScoreLineage.from_run(plan.plugin_identity, plugin.score_columns()).lineage_id. Because a generated ID includes the
runtime and the plugin release, a plugin or image upgrade reuses its predecessor's scores only once you accept them. A
plugin has one plugin_version for its code and its scoring together.
The prioritization rule, its annotation dependencies and the rest of the manifest are not part of the run identity. Changing only those keeps the lineage, so the new rule applies to the stored scores without scoring again.
Every accepted score still belongs to the requested model and input genome. An accepted lineage must belong to the requested plugin and supply output columns of compatible types. A declared nullable output may hold NULL, which differs from an output the lineage's schema lacks. Reading a subset of a run's columns does not create a new identity. An output selection that changes inference or reduction is part of the run identity, and reuse never equates two such runs.
read_selected_scores takes the same arguments and returns StoredScore objects with the values and the lineage
they came from. A variant's row comes whole from one lineage; columns from different lineages are never combined. When
a BigQuery lineage holds duplicate rows for a variant, the newest created_at wins, then a stable comparison of the
whole row.
To apply the same policy when you assemble results, pass ScoredModel(..., reuse_policy=reuse). Assembled results
include each model's score_lineages. plugin_identities holds only run metadata Altar recorded, so an imported
lineage has none. BigQuery exports and the tables the materialize_*_table calls write keep the lineage IDs too.
Equivalent lineages¶
A binding can declare two lineages scientifically equivalent, such as two images of one model runtime, with its
equivalence_projection. Lineage IDs never change; equivalence is decided when scores are read. To apply it, a store
needs each lineage's LineageDescriptor, the inputs its ID was hashed from. The store keeps the descriptors beside the
catalog: in {lineage_table_id}__descriptors in BigQuery, and _altar_score_lineages__descriptors in SQLite.
descriptor = plugin.scoring_lineage_descriptor_for(request)
await store.record_lineage_descriptor(plan.plugin_identity, descriptor) # verified first; no registration needed
resolution = await store.resolve_lineages(
plan.plugin_identity,
plugin.score_columns(),
reuse,
lineage_descriptor=descriptor,
equivalence=plugin,
)
resolution.lineage_ids # current, then registered equivalents by ID, then reuse's accepted IDs
resolution.steps # ResolutionStep.CURRENT / EQUIVALENT / ACCEPTED for each
resolution.rules_id # plugin.equivalence_rules_id, or None when no equivalence step ran
A Resolution is a tuple of the resolved ScoreLineage values, so it can be passed wherever lineages are expected.
Equivalents come only from lineages that are registered and have a recorded descriptor. The current lineage's
descriptor is the one you pass, checked against the identity and refused on a mismatch, or else the recorded one.
Without equivalence=plugin, or with no descriptor for the current lineage, the resolution is the current lineage plus
the accepted ones. get_missing_scores, read_selected_scores, prepare_unscored_table and export_unscored take
the same two optional arguments. ScoredModel(..., lineage_descriptor=...) passes the descriptor to assembly, which
applies the model's plugin's rules.
To read a job back with exactly the lineages it was admitted with, freeze the resolution:
ScoreReusePolicy.exactly(resolution.lineage_ids). The first ID must be the run's current lineage, which need not be
registered; every other ID must be registered.
A lineage has no descriptor until one is recorded:
attach_lineage_descriptorstakes(identity, descriptor)pairs, records every pair that verifies, and reports the attached, unregistered and failed ones.lineages_without_descriptors(plugin_id)lists the registered lineages still missing one.- The write paths,
primary_write,promote_staged_scores,add_scores_frameandregister_score_lineage, record a descriptor you pass them.
SQLite creates its descriptor table on the first descriptor it records. BigQuery never creates it on its own. Create it
with store.ensure_descriptor_table(), or yourself with the columns score_lineage_id STRING, plugin_id STRING,
descriptor_json STRING, recorded_at TIMESTAMP, clustered on plugin_id, score_lineage_id; extra nullable columns are
allowed. A missing descriptor table reads as empty, and recording into it fails with the table's name.
Reuse scores while preparing a cohort¶
Pass reuse_policy=reuse to prepare_scoring_batches. It filters the whole cohort against the accepted lineages
before it packs the misses into batches, as Prepare cache misses before
requests describes. The returned preparation keeps the policy.
On a store that keeps lineages, preparation first records the run's descriptor, derived from the plan, whether or not
anything is then scored. It then resolves the run's lineages once, with the plugin's equivalence rules and reuse as
the policy, including an exactly policy. The primary, detail and artifact checks all read that one resolution, and
the summary returns it as preparation.resolution. Read the job back with
ScoreReusePolicy.exactly(preparation.resolution.lineage_ids), as altar run does for its export. On a store without
lineages, preparation.resolution is None, and the checks read reuse as given.
run_scoring and ingest_scoring_results record the same descriptor when they declare the run, so the lineage they
register takes part in equivalence. A store without lineages records nothing. On a BigQuery store whose descriptor table
does not exist:
- an explicit recording call raises
DescriptorTableNotProvisioned, aCapabilityNotSupportedthat names the table; - the scoring calls run without recording, and emit one
DescriptorTableNotProvisionedWarningper store object.
Equivalence stays off at read time until the table exists.
Scoring always writes the current run's own identity. Its last duplicate check reads that identity, so an accepted older row never stops a deliberately recomputed result from being stored beside it.
For a warehouse-scale cohort, pass the same reuse_policy to BigQueryScoreStore.prepare_unscored_table, which keeps
the candidates and the misses in BigQuery; see Export unscored variants.
Details and artifacts follow the same rules¶
Detail rows and artifact records are written under the lineage of the run that produced them, the lineage its primary rows carry. A variant reused from an accepted lineage is a cache hit only when that lineage also holds its detail rows and selected artifacts, in a table or artifact with the same name, version and field meanings. Otherwise the variant is scored again, so a reused primary score is never paired with details of another shape; see Bindings with named details.
Accepting a lineage does not tell a failed biological prediction from a completed valid score.
Before you switch a production BigQuery table to lineages, try the switch in a scratch dataset; see Run at warehouse scale on BigQuery. Local tests do not measure warehouse cost or performance on a multi-terabyte score table.
Next¶
- Write a prioritization rule changes which stored scores are prioritized, without scoring again.
- Score reuse and provenance explains when a run reuses a score.
- Run at warehouse scale on BigQuery finds a cohort's cache misses in SQL.