quantlab.label.predefined.fret.BinaryReturn

class quantlab.label.predefined.fret.BinaryReturn(factor_config)

Bases: _OpenToOpenLabel

Forward n-bar open-to-open direction label.

At signal timestamp t the label is 1.0 when adjOpen[t + n + 1] / adjOpen[t + 1] - 1 > 0, 0.0 when that return is zero or negative, and NaN when it is NaN: the position is entered at the next bar’s adjusted open and judged n bars later at the adjusted open. The label is therefore NaN exactly where Return of the same horizon is NaN: where either open is missing (a gap in the prices, a symbol not yet listed or already delisted) and at timestamps without n + 1 later bars in the dataset. It is a Forward label with span = n and delay = 1.

The output column is ret_binary_{n}.

Parameters:

factor_configFactorConfig

The KunQuant factor config of the trailing indicator. Set data_columns to ["adjOpen"] and kwargs["n_forward_periods"] to the horizon n.

Examples

One symbol whose open on 3 January is missing. The labels on 1 and 2 January read that open and are NaN, like the last two, which have no two later bars.

>>> import numpy as np, pandas as pd, xarray as xr
>>> from quantlab.backend.zarr import XrBackend
>>> from quantlab.factor.config import FactorConfig
>>> from quantlab.dataset.config import DatasetConfig
>>> from quantlab.dataset.stock import StockDataset
>>> from quantlab.label.predefined.fret import BinaryReturn, Return
>>> opens = np.array([10.0, 11.0, np.nan, 12.0, 11.0, 13.0, 12.0, 14.0])
>>> XrBackend().to_internal(xr.Dataset(
...     {"adjOpen": (["timestamp", "symbol"], opens[:, None])},
...     coords={"timestamp": pd.date_range("2024-01-01", periods=8), "symbol": ["A"]},
... )).write("data/stock.zarr")
XrBackend()
>>> dataset = StockDataset(DatasetConfig(
...     raw_data_dir_path="data/raw", zarr_file_path="data/stock.zarr",
...     market="us_equity", frequency="1d",
... ))
>>> config = dict(
...     warmup_bars=1, dataset=dataset, mode="batch", data_columns=["adjOpen"],
...     kwargs={"n_forward_periods": 1}, njobs=1,
... )
>>> ret = Return(FactorConfig(file_path="data/ret.zarr", **config))
>>> up = BinaryReturn(FactorConfig(file_path="data/up.zarr", **config))
>>> up.get_factor_names()
('ret_binary_1',)
>>> ret.compute("2024-01-01", "2024-01-08")["ret_1"].values[:, 0].round(3)
array([   nan,    nan, -0.083,  0.182, -0.077,  0.167,    nan,    nan],
      dtype=float32)
>>> up.compute("2024-01-01", "2024-01-08")["ret_binary_1"].values[:, 0]
array([nan, nan,  0.,  1.,  0.,  1., nan, nan], dtype=float32)