quantlab.runs.directory

Run directories: the mechanism every run type of quantlab is written and read through.

A run is a directory. It holds its files and, written last, run.json, the record that makes the directory a run: a directory without it is not a run, so a crash can never leave one that opens. Every run.json starts with the same header:

• format_version: one version shared by every run type (FORMAT_VERSION); a run written in another version is refused with a message to re-run or retrain it, never read wrongly;

• kind: what the run is, which decides the type open_run returns;

• written_at: when the record was written, an ISO 8601 UTC timestamp.

The rest of the record belongs to the run type. Paths inside it are relative to the run’s directory (relative_name / recorded_path), so a run copied elsewhere still opens. A run whose files are written at once can be written through staged: into a hidden sibling first, renamed into place when complete.

The run types are quantlab.runs.trained_run.TrainedRun (kinds "model", "ensemble", "walk_forward") and quantlab.runs.backtest_run.BacktestRun (kinds "run", "run_cv", "run_weights", "fold"). open_run reads any run and returns its type, which is imported only when a run of that kind is opened.

This module imports no quantlab module outside quantlab.utils; the run types in KINDS are named by import path and imported only by open_run.

Examples

>>> run = open_run("models/MyHead_trial_20240601_120000_000000")
>>> type(run).__name__, run.kind
('TrainedRun', 'model')

Functions

open_run	Read the run at path as the type its kind names.
read_record	Return the run.json of the run in directory, after checking its header.
record_path	Return where the run.json of the run in directory is.
recorded_path	Return the path a run.json entry names, or None when nothing is recorded.
relative_name	Return path relative to the run directory, as recorded in run.json.
run_directory	Return the run directory of path: path itself, or the directory of a file in it.
staged	Yield a hidden staging directory that becomes final when the block succeeds.
write_record	Write record as the run.json of directory, atomically, under the header.