quantlab.model.library_model.LibraryModel

class quantlab.model.library_model.LibraryModel(config)

Bases: TrainingTargetMixin, BaseModel

Numpy variant for tree models and other non-torch libraries.

There is no epoch loop and no copy-based rollback. Training, early stopping and the choice of the best model are left to the library’s own mechanism inside _fit_model: boosting libraries decide early stopping per round with cached validation scores, and rolling back to the best round is a matter of keeping the first k trees, both of which an outer epoch loop would only make coarser and slower.

The base builds the rows. The training target is computed once per fit, one bar at a time, by _transform_target (training=True on the training bars only), exactly as for a torch head. Only cells with a valid training target become rows; NaN features are kept, so the library’s own missing-value handling decides what they mean. Each row carries its cell in where (see Rows).

hyperparameters["training_target"] picks the training target without a subclass: "cs_rank" (cs_rank_norm) or "cs_zscore" (cs_zscore), applied on the training, validation and test bars alike, so early stopping watches the validation loss on the training target; unset trains on the raw label. label_scales then reports "standardized" for every label. A head that overrides _transform_target itself ignores the setting.

A head implements three hooks: _init_model, _fit_model and _forward. _transform_feature (inf to NaN), _transform_target (training_target, else the raw label), _loss (MSE), and the inherited _resolved_hyperparameters have defaults that may be overridden. {split}_loss is _loss on the training target per bar, averaged over bars; the other metrics come from the model’s evaluation after training (see BaseModel._evaluate). Checkpoints are .joblib files written with joblib.dump; they are pickles, so only load files you trust.

Examples

A minimal head that predicts the first feature for every label:

>>> class FirstFeatureHead(LibraryModel):
...     def _init_model(self, num_features, num_labels, hyperparameters):
...         return {"num_labels": num_labels}
...     def _fit_model(self, train_rows, val_rows):
...         pass
...     def _forward(self, x):
...         return np.repeat(x[:, :1], self.model["num_labels"], axis=-1)
>>> head = FirstFeatureHead(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-01-30",
...     test_start="2024-01-31", test_end="2024-02-09",
... ))
>>> head.collect().train().suffix
'.joblib'

check_hyperparameters()

Refuse an invalid training_target.

Raises:

ValueError

If training_target is not a known transform.

Examples

>>> model.check_hyperparameters()  # no training_target set

property early_stopping

hyperparameters["early_stopping"], False when unset.

Whether the head turns on its library’s native early stopping.

Examples

>>> head.early_stopping
False

property early_stopping_patience

hyperparameters["early_stopping_patience"], 5 when unset.

Rounds (or the library’s own unit) without improvement before the library’s early stopping triggers.

Examples

>>> head.early_stopping_patience
5

reserved_hyperparameters = frozenset({'early_stopping', 'early_stopping_patience', 'training_target'})

The hyperparameters keys this variant reads itself, which head_hyperparameters leaves out.

property training_target

hyperparameters["training_target"], None when unset.

Raises:

ValueError

If it is set to anything but "cs_rank" or "cs_zscore".

Examples

>>> head.training_target is None
True