quantlab.model.predefined.master.MASTERRegressor#

class quantlab.model.predefined.master.MASTERRegressor(config)[source]#

Bases: TorchModel

MASTER on the cross-section of every bar, gated by the gate_features factors.

Each step is one bar: every symbol with a finite feature, each with its last window_bars bars, goes through MASTERNet. The factors named by hyperparameters["gate_features"] are the market features (for example those of quantlab.factor.predefined.market, the same at every symbol); every other factor is a stock feature they gate. In training the label’s top and bottom drop_extreme share leave the loss, and the rest is z-scored per bar; validation and test targets are z-scored only. The loss is the MSE over symbols with a target, the optimizer is Adam, and gradient values are clipped at 3. Training stops at the first epoch whose training loss is at or below train_loss_threshold, or after epochs, and keeps the last weights, as the official code does.

Hyperparameters, with the official values as defaults: gate_features (required), window_bars (8), d_model (256), t_nhead (4), s_nhead (2), dropout (0.5), beta (5.0; the paper uses 2 for CSI800), lr (1e-5), epochs (40), train_loss_threshold (0.95) and drop_extreme (0.025).

Known differences from the official implementation:

the market features are whatever gate_features names, for US equities the SPY/QQQ/IWM features of the market factor rather than the CSI300/500/800 indices;
a symbol dropped by drop_extreme leaves the loss but stays in the bar’s cross-section as context; the official code removes it from that day’s input too;
no RobustZScoreNorm is fitted on the training span: the default _transform_feature clips to ±3 and fills NaN with 0, where the official data forward- and back-fills gaps inside a window;
the output has one column per label instead of one.

Parameters:

configModelConfig: Factors, labels, dates and hyperparameters.

Raises:

ValueError: If gate_features is missing or empty, names a factor the model does not have (the error lists them), or names every factor.

Examples

>>> head = MASTERRegressor(ModelConfig(
...     factors=[factor], labels=[label], model_save_dir="checkpoints",
...     factor_data_strategy="read", label_data_strategy="read",
...     train_start="2024-01-01", train_end="2024-05-31",
...     test_start="2024-06-01", test_end="2024-07-18",
...     hyperparameters={"gate_features": ["f_b"], "window_bars": 5,
...                      "d_model": 16, "epochs": 5},
... )).collect()
>>> head.train().name
'MASTERRegressor_total.pth'

DEFAULTS = {'beta': 5.0, 'd_model': 256, 'drop_extreme': 0.025, 'dropout': 0.5, 'epochs': 40, 'lr': 1e-05, 's_nhead': 2, 't_nhead': 4, 'train_loss_threshold': 0.95, 'window_bars': 8}#: The official values, used for every unset hyperparameter.

property epochs#

The epoch cap, hyperparameters["epochs"], 40 when unset.

Raises:

ValueError: If the value is not a positive integer.

Examples

>>> head.epochs
5

property gate_columns#

Positions of the gate_features factors in get_factor_names().

Raises:

ValueError: If gate_features is missing or empty, names a factor the model does not have, or names every factor.

Examples

>>> head.get_factor_names(), head.gate_columns
(['f_a', 'f_b'], [1])

property window_bars#

Bars in each symbol’s window, hyperparameters["window_bars"] (8).

Examples

>>> head.window_bars
5