manager.models.forecaster_recursive_model_full

manager.models.forecaster_recursive_model_full

Full-featured base forecasting model with Bayesian tuning and SHAP.

This module extends :class:~spotforecast2_safe.manager.models.forecaster_recursive_model.ForecasterRecursiveModel from spotforecast2-safe with real Bayesian hyperparameter search (Optuna) and SHAP-based feature importance (shap.TreeExplainer).

Examples

>>> from spotforecast2.manager.models import ForecasterRecursiveModelFull
>>> model = ForecasterRecursiveModelFull(iteration=0)
>>> hasattr(model, 'tune')
True
>>> hasattr(model, 'get_global_shap_feature_importance')
True

Classes

Name	Description
ForecasterRecursiveModelFull	ForecasterRecursiveModel with real Bayesian tuning and SHAP.

ForecasterRecursiveModelFull

manager.models.forecaster_recursive_model_full.ForecasterRecursiveModelFull(
    iteration,
    n_trials=_DEFAULT_N_TRIALS,
    **kwargs,
)

ForecasterRecursiveModel with real Bayesian tuning and SHAP.

This class overrides the two stubs in spotforecast2-safe:

• :meth:tune — performs a full Bayesian hyperparameter search using bayesian_search_forecaster (Optuna).
• :meth:get_global_shap_feature_importance — computes global SHAP values using shap.TreeExplainer.

Parameters

Name	Type	Description	Default
iteration	int	Training iteration index (0-based).	required
n_trials	int	Number of Optuna trials for Bayesian search.	_DEFAULT_N_TRIALS
**kwargs	Any	Forwarded to :class:ForecasterRecursiveModel.	{}

Examples

>>> from spotforecast2.manager.models import ForecasterRecursiveModelFull
>>> model = ForecasterRecursiveModelFull(iteration=0)
>>> model.n_trials
10
>>> model.iteration
0
>>> hasattr(model, 'tune')
True
>>> hasattr(model, 'get_global_shap_feature_importance')
True

Methods

Name	Description
get_global_shap_feature_importance	Return global SHAP-based feature importances.
tune	Tune the forecaster via Bayesian search (Optuna).

get_global_shap_feature_importance

manager.models.forecaster_recursive_model_full.ForecasterRecursiveModelFull.get_global_shap_feature_importance(
    frac=0.1,
)

Return global SHAP-based feature importances.

Uses shap.TreeExplainer on the underlying estimator to compute mean absolute SHAP values across a random sample of the training data.

Parameters

Name	Type	Description	Default
frac	float	Fraction of training data to sample (0 < frac <= 1).	0.1

Returns

Name	Type	Description
	pd.Series	pd.Series: Feature importances sorted descending. Empty
	pd.Series	if the model has not been tuned.

Raises

Name	Type	Description
	ValueError	If the forecaster has not been initialized.

Examples

>>> from spotforecast2.manager.models import ForecasterRecursiveLGBMFull
>>> model = ForecasterRecursiveLGBMFull(iteration=0)
>>> # Returns empty Series when model is not tuned
>>> result = model.get_global_shap_feature_importance()
>>> import pandas as pd
>>> isinstance(result, pd.Series)
True

tune

manager.models.forecaster_recursive_model_full.ForecasterRecursiveModelFull.tune(
)

Tune the forecaster via Bayesian search (Optuna).

Loads time-series data, builds exogenous features, and runs bayesian_search_forecaster over the search space registered for self.name in SEARCH_SPACES.

After tuning the model is fitted with the best parameters and, if self.save_model_to_file is True, persisted to disk.

Raises

Name	Type	Description
	KeyError	If self.name is not in SEARCH_SPACES.

Examples

>>> from spotforecast2.manager.models import ForecasterRecursiveLGBMFull
>>> model = ForecasterRecursiveLGBMFull(iteration=0)
>>> callable(model.tune)
True