models.forecaster_recursive_xgb_full

models.forecaster_recursive_xgb_full

XGBoost forecaster with real Bayesian tuning and SHAP.

This module provides ForecasterRecursiveXGBFull, which combines the XGBoost forecaster from spotforecast2-safe with Bayesian hyperparameter optimisation (Optuna) and SHAP-based feature importance from ForecasterRecursiveModelFull.

Examples

import numpy as np
import pandas as pd
from xgboost import XGBRegressor

from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
from spotforecast2.models import ForecasterRecursiveXGBFull

model = ForecasterRecursiveXGBFull(iteration=0, lags=3)
# Swap in a tiny estimator so the example renders quickly.
model.forecaster = ForecasterRecursive(
    estimator=XGBRegressor(n_estimators=5, max_depth=2, random_state=1234),
    lags=3,
)
assert model.name == "xgb"
assert model.n_trials == 10

rng = np.random.default_rng(0)
y = pd.Series(
    rng.random(30),
    index=pd.date_range("2023-01-01", periods=30, freq="h"),
)
model.fit(y=y)
pred = model.forecaster.predict(steps=2)
assert len(pred) == 2
print(f"name: {model.name}")
print(f"n_trials: {model.n_trials}")
print(f"forecast horizon: {len(pred)} steps")

╭─────────────────────────────── IgnoredArgumentWarning ───────────────────────────────╮
│ The number of bins has been reduced from 10 to 9 due to duplicated edges caused by   │
│ repeated predicted values.                                                           │
│                                                                                      │
│ Category : spotforecast2.exceptions.IgnoredArgumentWarning                           │
│ Location :                                                                           │
│ /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages/spotforecast2_s │
│ afe/preprocessing/_binner.py:259                                                     │
│ Suppress : warnings.simplefilter('ignore', category=IgnoredArgumentWarning)          │
╰──────────────────────────────────────────────────────────────────────────────────────╯

name: xgb
n_trials: 10
forecast horizon: 2 steps

Classes

Name	Description
ForecasterRecursiveXGBFull	XGBoost forecaster with real Bayesian tuning and SHAP.

ForecasterRecursiveXGBFull

models.forecaster_recursive_xgb_full.ForecasterRecursiveXGBFull(
    iteration,
    lags=12,
    **kwargs,
)

XGBoost forecaster with real Bayesian tuning and SHAP.

Inherits the XGBoost forecaster initialisation from ForecasterRecursiveXGB (spotforecast2-safe) and adds the real tune() and get_global_shap_feature_importance() from ForecasterRecursiveModelFull.

The MRO ensures that tune() and SHAP methods resolve from ForecasterRecursiveModelFull, while the XGBoost-specific __init__ (estimator wiring) comes from ForecasterRecursiveXGB.

Parameters

Name	Type	Description	Default
iteration	int	Training iteration index (0-based).	required
lags	int	Number of lag features to use.	`12`
**kwargs	Any	Forwarded to parent classes (e.g., `n_trials`, `predict_size`, `train_size`).	`{}`

Examples

import numpy as np
import pandas as pd
from xgboost import XGBRegressor

from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
from spotforecast2.models import ForecasterRecursiveXGBFull

model = ForecasterRecursiveXGBFull(iteration=0, lags=3)
# Swap in a tiny estimator so the example renders quickly.
model.forecaster = ForecasterRecursive(
    estimator=XGBRegressor(n_estimators=5, max_depth=2, random_state=1234),
    lags=3,
)
assert model.name == "xgb"
assert model.iteration == 0
assert model.n_trials == 10
assert callable(model.tune)
assert callable(model.get_global_shap_feature_importance)

rng = np.random.default_rng(0)
y = pd.Series(
    rng.random(30),
    index=pd.date_range("2023-01-01", periods=30, freq="h"),
)
model.fit(y=y)
pred = model.forecaster.predict(steps=2)
assert len(pred) == 2
print(f"name: {model.name}")
print(f"iteration: {model.iteration}")
print(f"n_trials: {model.n_trials}")
print(f"has tune: {callable(model.tune)}")
print(f"has SHAP: {callable(model.get_global_shap_feature_importance)}")
print(f"forecast horizon: {len(pred)} steps")

╭─────────────────────────────── IgnoredArgumentWarning ───────────────────────────────╮
│ The number of bins has been reduced from 10 to 9 due to duplicated edges caused by   │
│ repeated predicted values.                                                           │
│                                                                                      │
│ Category : spotforecast2.exceptions.IgnoredArgumentWarning                           │
│ Location :                                                                           │
│ /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages/spotforecast2_s │
│ afe/preprocessing/_binner.py:259                                                     │
│ Suppress : warnings.simplefilter('ignore', category=IgnoredArgumentWarning)          │
╰──────────────────────────────────────────────────────────────────────────────────────╯

name: xgb
iteration: 0
n_trials: 10
has tune: True
has SHAP: True
forecast horizon: 2 steps