Where results live¶
A run keeps a model's results in up to three stores, which last between runs, and writes an export, a table of this run's cohort. Each holds one shape of result:
| Place | Holds | Spec section | Lasts |
|---|---|---|---|
| Score store | One row of scores per variant and model | [store] |
Between runs |
| Detail store | Detail tables: a model's output with many rows per variant, such as one row per track | [detail_store], or beside the score store |
Between runs |
| Artifact store | Files a model writes that Altar keeps without reading, such as a matrix | [artifact_store] |
Between runs |
| Export | One row per variant of the cohort: scores, annotations and prioritization | [export] |
Written by each run |
Run spec lists each section's keys.
The score store¶
The score store keeps each model's primary scores: one row per variant and model key, with the columns the model's binding declares, such as a log fold change. A run with models needs one. Before it scores, the run asks the store which variants it already holds. After the last model, the export reads every model's scores from it.
[store] names a SQLite file, or a BigQuery table (Preview). Without it, a run with models keeps its scores in
SQLite in the cache, <cache_dir>/scores.sqlite. The scores of one model with one set of
score-changing settings are a lineage. A store with lineages keeps several lineages apart under one model key, and
a new SQLite store that altar run creates keeps lineages. Score reuse and provenance describes
lineages and when a stored score is reused.
Annotations are not kept between runs. Each run looks every variant up in its sources again.
Detail tables¶
Some models produce many values per variant, such as Enformer's effect on each selected track or Sei's effect on each sequence class. The binding declares these as named detail tables, and the model writes them on every run. Each row keeps its variant, its model key and the lineage of the score row it belongs to.
A model can reduce its detail rows to primary scores, such as the largest effect across tracks. Each model's page says how. The detail table keeps every value.
The run builds a detail store only for a model that declares detail tables. Without a [detail_store] section the
tables go beside the score store: for scores.sqlite, into scores.details.sqlite in the same directory.
Artifacts¶
An artifact is a file a model writes that Altar keeps as a file, without reading it, such as Sei's
chromatin-profile matrix. A model writes one only when its section's output selects it, and the spec then needs
an [artifact_store]. The storage artifact store copies each file to <cache_dir>/artifacts by default, and an
index records which variants each file covers.
A variant counts as already scored only when the stores hold its score row, its rows in every detail table the
model declares, and every artifact its output selects. A variant missing any of them is scored again.
The export¶
The export is the table one run writes: one row per variant of the cohort, with each model's primary scores, each
source's columns, the prioritized flag and the models and sources that set it. It is Parquet or gzipped TSV, in
<work_dir>/export unless [export] destination names another directory. A run summary, _run_summary.json,
sits beside it, and the export carries a provenance record. Read a run's results reads all
three.
The export holds no detail rows and no artifacts. Read them from their stores; see Read details and artifacts.
Why scores are stored¶
Running a model takes compute time and, for a hosted model, API requests. The score store keeps each model's scores, and a later run uses them:
- A cohort with new variants sends only the new ones to the model.
- A new source, a new prioritization threshold or a new export format runs no model.
- A run that stopped part way resumes at the first batch it did not store.
From Python, you can also read a store to assemble results for any variants it holds; see Store and assemble results.
The run directory and the cache¶
The run reads and writes files through [storage]: local paths by default, HTTPS URLs for reading, or any
filesystem fsspec supports, such as gs://. It keeps them in two directories.
The run directory, [run] work_dir, is <job_id> in the starting directory by default. It holds what only this
run reads:
variants/, the normalized cohort;staging/jobs/<job_id>/, the variant batches staged for this run's model tasks;results/jobs/<job_id>/, the files those tasks wrote;export/, unless[export] destinationnames another place.
The cache, [run] cache_dir, is .altar in the starting directory by default, or the ALTAR_CACHE_DIR
environment variable. It holds what a later run reads:
staging/models/, the filesaltar preparepublishes;scores.sqliteandscores.details.sqlite, when the spec names no[store];artifacts/andinterpretations/, unless the spec names other places, and the progress records of interpretations;backend-data/, the directory thelocalbackend mounts into containers.
Deleting a run directory loses no stored result, so a rerun with any job_id reuses what the cache holds. The
stores and the export hold the run's results; the staged and collected files are its working files.
Next¶
- Score reuse and provenance says when a stored score is reused and what the export records.
- Choose where results are stored sets up each store in a run spec.
- Read a run's results reads the export, the run summary and the detail tables.