energykit.forecast

Load forecasting with LightGBM or scikit-learn gradient boosting.

energykit.forecast — Load, price, solar and wind forecasting.

Bases: BaseEstimator

Energy load forecaster powered by gradient boosting + energy features.

Parameters:

horizon (int, default 24) – Default forecast horizon in periods (hours for hourly data).
lags (list of int or None) – Lag features to include. Defaults to [1, 2, 3, 24, 48, 168].
rolling_windows (list of int or None) – Rolling statistic windows. Defaults to [24, 168].
country (str or None) – ISO country code for holiday features (e.g. "US", "DE").
lat (float or None) – Coordinates for solar position features.
lon (float or None) – Coordinates for solar position features.
model_params (dict or None) – Override default LightGBM / HGBR hyperparameters.
tou_schedule (dict or None) – Custom time-of-use schedule passed to the feature extractor.

model_

The underlying gradient boosting model.

Type:: fitted regressor

feature_extractor_

Fitted feature extractor (stateless, but retains feature_names_).

Type:: EnergyFeatureExtractor

train_series_

The training series (kept for recursive prediction warm-start).

Type:: pd.Series

is_fitted_

True after fit() has been called.

Type:: bool

Examples

>>> model = LoadForecaster(horizon=24, country="US")
>>> model.fit(meter)
>>> fc = model.predict()

feature_importance() → Series[source]

Return feature importances sorted descending.

Works with LightGBM and sklearn HGBR.

Returns:: Feature name → importance score.
Return type:: pd.Series

fit(X: Series, y=None) → LoadForecaster[source]

Train the forecaster on historical load data.

Parameters:: X (pd.Series) – Hourly smart-meter or aggregated load readings with a DatetimeIndex. Gaps and NaN values are forward-filled before training.
Return type:: self

predict(horizon: int | None = None, last_known: Series | None = None) → Series[source]

Generate a multi-step ahead load forecast.

Parameters:

horizon (int or None) – Forecast horizon in periods. Defaults to self.horizon.
last_known (pd.Series or None) – Provide a different warm-start series (e.g. latest observations from production). Defaults to the training series.

Returns:

Forecasted values with a DatetimeIndex starting at last_known.index[-1] + freq.

Return type:

pd.Series

set_predict_request(*, horizon: bool | None | str = '$UNCHANGED$', last_known: bool | None | str = '$UNCHANGED$') → LoadForecaster

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to predict.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

horizon (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for horizon parameter in predict.
last_known (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for last_known parameter in predict.

Returns:

self – The updated object.

Return type:

object

Load Forecaster