quantlab.model.predefined.xgb_td.XGBTDRegressor#

class quantlab.model.predefined.xgb_td.XGBTDRegressor(config)[source]#

Bases: TabkitRegressor

Predict future returns with pytabkit’s tuned-default XGBoost.

self.model is a list with one fitted estimator per label, in get_label_names() order, because pytabkit’s XGBoost estimator does not support multi-output regression. Every estimator is trained on the same rows: the cells whose training target is valid in every label. Headline metrics are computed on the primary label, index 0. NaN imputation and the hyperparameter record are inherited from TabkitRegressor.

Hyperparameters are the constructor arguments of XGB_TD_Regressor (n_estimators, max_depth, lr, subsample, n_threads, device, …). Unless device is given, training runs on "cuda" when xgboost can train on CUDA here and on "cpu" otherwise, never on Apple MPS (the rule of XGBoostRegressor). pytabkit forwards no device to xgboost, so the head injects it into pytabkit’s inner xgboost.train call; the device is recorded in resolved_hyperparameters. The Boosters stay on that device in memory; the checkpoint is written with device="cpu" so it loads without CUDA, and a loaded model is placed on the default device by the same rule. pytabkit’s tuned defaults fill in whatever is not given: 1000 rounds, depth 9, learning rate 0.05, subsample 0.7.

With validation rows, pytabkit always selects the round with the lowest validation error, so the .joblib checkpoint predicts with the best round, and that round count is written to the run summary as best_n_estimators (primary label) and best_n_estimators/{label} (every label). With hyperparameters["early_stopping"] set, training additionally halts after hyperparameters["early_stopping_patience"] rounds without improvement; the value is recorded as early_stopping_rounds in resolved_hyperparameters (None when off). Without a usable validation segment a warning is logged, all rounds are trained and the estimator is pinned to predict with all of them (see _pin_all_rounds). No per-round curve is logged.

train_cv (rolling walk-forward cross-validation) is inherited. Each fold selects its own best round and writes its own .joblib. The folds train one after another.

Every tracking run gets, per label, the validation curve of each boosting round (val-rmse, or val-rmse/<label> with several labels, at step=round), the selected round (best_n_estimators), the rounds trained (num_boosted_rounds) and the per-factor importance with its tables, exactly as XGBoostRegressor records them. The callback is injected into pytabkit’s inner xgboost.train call (see quantlab.model.predefined._support.tabkit.active_callbacks).

Parameters:

configModelConfig: Factors, labels, date ranges, early-stopping settings and hyperparameters. See ModelConfig.

Examples

>>> config = ModelConfig(
...     factors=[alpha],            # factor objects
...     labels=[fwd_return],        # label objects
...     model_save_dir="checkpoints",
...     factor_data_strategy="read",
...     label_data_strategy="read",
...     train_start="2024-01-01", train_end="2024-02-09",
...     test_start="2024-02-10", test_end="2024-02-29",
...     hyperparameters={
...         "early_stopping": True, "early_stopping_patience": 50,
...         "n_estimators": 500, "n_threads": 4,
...     },
... )
>>> model = XGBTDRegressor(config)
>>> checkpoint = model.collect().train()
>>> checkpoint.name
'XGBTDRegressor_total.joblib'
>>> model.predict(np.zeros((5, 2, 3), dtype="float32")).shape
(5, 2, 1)
>>> model.train_cv(train_periods=500)

DEFAULT_PARAMS = {'val_fraction': 0.0, 'verbosity': 0}#: Estimator constructor arguments applied before the config seed, the early-stopping keys and the user’s hyperparameters.