quantlab.runs.prediction_panel.PredictionPanel#

class quantlab.runs.prediction_panel.PredictionPanel(predictions, labels)[source]#

Bases: object

A run’s predictions together with the specs of the labels they predict.

Every backtest run with a model writes the predictions its rule read as a prediction panel (quantlab.runs.backtest_run.BacktestRun.predictions): one variable per label on (timestamp, symbol), the store’s attrs holding format_version (FORMAT_VERSION) and labels, a JSON list of the specs’ fields. An executor rebuilds the run’s decision inputs, the rule bound to these specs included, with quantlab.portfolio.decision_inputs.DecisionInputs.from_run.

Parameters:

predictionsxr.Dataset: One variable per label, each on (timestamp, symbol), named exactly as labels name them; NaN where a symbol has no prediction.
labelsSequence[LabelSpec]: The label specs, in the order of the prediction variables; stored as a tuple.

Raises:

ValueError: If the label names repeat, the variables are not exactly the label names, or a variable is not on (timestamp, symbol).

Examples

>>> import numpy as np, pandas as pd, xarray as xr
>>> from quantlab.runs.prediction_panel import LabelSpec
>>> predictions = xr.Dataset(
...     {"ret_5": (("timestamp", "symbol"), np.array([[0.1, -0.2], [0.3, np.nan]]))},
...     coords={"timestamp": pd.date_range("2024-01-02", periods=2),
...             "symbol": np.array(["AAA", "BBB"], dtype=object)},
... )
>>> panel = PredictionPanel(predictions, [LabelSpec("ret_5", "raw", 1, 5)])
>>> panel.labels
(LabelSpec(name='ret_5', scale='raw', delay=1, span=5),)

FORMAT_VERSION = 1#: The version of the store layout write writes and read reads.

classmethod read(path)[source]#

Read a panel write stored, into memory.

Parameters:

pathstr or os.PathLike: Directory of the store.

Returns:

PredictionPanel: The predictions, without the store’s attrs, and the specs.

Raises:

FileNotFoundError: If path does not exist.
ValueError: If the store is not a prediction panel of FORMAT_VERSION.

Examples

>>> PredictionPanel.read(path).predictions["ret_5"].dims
('timestamp', 'symbol')

classmethod read_labels(path)[source]#

Read only the label specs of the panel stored at path.

The store is opened lazily and no prediction is loaded.

Parameters:

pathstr or os.PathLike: Directory of the store.

Returns:

tuple[LabelSpec, …]: The specs, in the order of the prediction variables.

Raises:

FileNotFoundError: If path does not exist.
ValueError: If the store is not a prediction panel of FORMAT_VERSION.

Examples

>>> PredictionPanel.read_labels(path)
(LabelSpec(name='ret_5', scale='raw', delay=1, span=5),)

write(path)[source]#

Write the panel to the Zarr store path, replacing any store there.

The variables are written as they are; the store’s attrs are exactly format_version and labels (the specs’ fields as a JSON list).

Parameters:

pathstr or os.PathLike: Directory of the store, <run_dir>/predictions.zarr in a run.

Returns:

Path: path.

Examples

>>> import tempfile
>>> path = panel.write(Path(tempfile.mkdtemp()) / "panel.zarr")
>>> PredictionPanel.read(path).labels == panel.labels
True