LGBMLinearForecaster#

class openstef_models.models.forecasting.lgbmlinear_forecaster.LGBMLinearForecaster(**data: Any) → None[source]

Bases: Forecaster, ExplainableForecaster, ContributionsMixin

LGBMLinear-based forecaster for probabilistic energy forecasting.

Implements gradient boosting trees with linear leaves using LightGBM for multi-quantile forecasting. Optimized for time series prediction with specialized loss functions and comprehensive hyperparameter control suitable for production energy forecasting.

The forecaster uses a multi-output strategy where each quantile is predicted by separate trees within the same boosting ensemble. This approach provides well-calibrated uncertainty estimates while maintaining computational efficiency.

Invariants

  • fit() must be called before predict() to train the model

  • Configuration quantiles determine the number of prediction outputs

  • Model state is preserved across predict() calls after fitting

  • Input features must match training data structure during prediction

Example

Basic forecasting workflow

>>> from datetime import timedelta
>>> from openstef_core.types import LeadTime, Quantile
>>> forecaster = LGBMLinearForecaster(
...     quantiles=[Quantile(0.1), Quantile(0.5), Quantile(0.9)],
...     horizons=[LeadTime(timedelta(hours=1))],
...     hyperparams=LGBMLinearHyperParams(n_estimators=100, max_depth=6),
... )
>>> forecaster.fit(training_data)
>>> predictions = forecaster.predict(test_data)

Note

LightGBM dependency is optional and must be installed separately. The model automatically handles multi-quantile output and uses magnitude-weighted pinball loss by default for better forecasting performance.

See also

LGBMLinearHyperParams: Detailed hyperparameter configuration options. Forecaster: Base interface for all forecasting models. GBLinearForecaster: Alternative linear model using XGBoost.

Parameters:

data (Any)

HyperParams

alias of LGBMLinearHyperParams

hyperparams: LGBMLinearHyperParams
device: str
n_jobs: int
verbosity: Literal[-1, 0, 1, 2, 3]
random_state: int | None
early_stopping_rounds: int | None
property hparams: LGBMLinearHyperParams

Model hyperparameters for training and prediction.

Concrete forecasters implement this by returning their narrowed hyperparams field, giving callers a polymorphic read-only view while each subclass keeps full type safety on its own field.

model_post_init(_context: object, /) → None[source]

Initialize the underlying LightGBM linear model from configuration.

Raises:

MissingExtraError – If lightgbm is not installed.

Parameters:

_context (object)

Return type:

None

property is_fitted: bool

Check if the predictor has been fitted.

fit(data: ForecastInputDataset, data_val: ForecastInputDataset | None = None) → None[source]

Fit the predictor to the input data.

This method should be called before generating predictions. It allows the predictor to learn parameters from the training data.

Parameters:
Return type:

None

predict(data: ForecastInputDataset) → ForecastDataset[source]

Generate predictions for the input data.

This method should use the fitted parameters to generate predictions.

Parameters:
Returns:

Predictions for the input data.

Raises:

NotFittedError – If the predictor has not been fitted yet.

Return type:

ForecastDataset

predict_contributions(data: ForecastInputDataset) → TimeSeriesDataset[source]

Compute SHAP feature contributions for the median quantile.

Parameters:
Returns:

TimeSeriesDataset with per-feature SHAP values plus a bias column.

Raises:

NotFittedError – If the model has not been fitted.

Return type:

TimeSeriesDataset

property feature_importances: DataFrame

Get feature importance scores for this model.

Returns DataFrame with feature names as index and quantiles as columns. Each quantile represents the importance distribution across multiple model training runs or folds.

Returns:

DataFrame with feature names as index and quantile columns. Values represent normalized importance scores summing to 1.0.

Note

The returned DataFrame must have feature names as index and quantile columns in format ‘quantile_PXX’ (e.g., ‘quantile_P50’, ‘quantile_P95’). All quantile values must be between 0 and 1.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'protected_namespaces': ()}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].