openstef-models 4.1.1.dev0__tar.gz → 4.2.1__tar.gz

{openstef_models-4.1.1.dev0 → openstef_models-4.2.1}/.gitignore

@@ -71,6 +71,8 @@ docs/source/user_guide/**/quick_start_tutorial.py
 docs/source/user_guide/**/feature_engineering_tutorial.py
 docs/source/user_guide/**/datasets_tutorial.py
 docs/source/user_guide/**/backtesting_tutorial.py
+docs/source/user_guide/**/foundation_model_forecasting_quickstart.py
+docs/source/user_guide/**/foundation_model_forecasting.py
 
 # docs/_doctrees/
 # docs/_static_gen/

{openstef_models-4.1.1.dev0 → openstef_models-4.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openstef-models
-Version: 4.1.1.dev0
+Version: 4.2.1
 Summary: Core models for OpenSTEF
 Project-URL: Documentation, https://openstef.github.io/openstef/index.html
 Project-URL: Homepage, https://lfenergy.org/projects/openstef/

{openstef_models-4.1.1.dev0 → openstef_models-4.2.1}/pyproject.toml

@@ -7,7 +7,7 @@ requires = [ "hatchling" ]
 
 [project]
 name = "openstef-models"
-version = "4.1.1.dev0"
+version = "4.2.1"
 description = "Core models for OpenSTEF"
 readme = "README.md"
 keywords = [ "energy", "forecasting", "machinelearning" ]

{openstef_models-4.1.1.dev0 → openstef_models-4.2.1}/src/openstef_models/models/forecasting/lgbm_forecaster.py

@@ -111,6 +111,12 @@ class LGBMHyperParams(HyperParams):
         description="Fraction of features used when constructing each tree. Range: (0,1]",
     )
 
+    # Early Stopping
+    early_stopping_rounds: int | None = Field(
+        default=None,
+        description="Training will stop if performance doesn't improve for this many rounds. Requires validation data.",
+    )
+
     @classmethod
     def forecaster_class(cls) -> "type[LGBMForecaster]":
         """Create a LightGBM forecaster instance from this configuration.
@@ -184,10 +190,6 @@ class LGBMForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
         alias="seed",
         description="Random seed for reproducibility.",
     )
-    early_stopping_rounds: int | None = Field(
-        default=None,
-        description="Training stops if performance doesn't improve for this many rounds.",
-    )
 
     _lgbm_model: MultiQuantileRegressor = PrivateAttr()
 
@@ -229,7 +231,7 @@ class LGBMForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
             "colsample_bytree": self.hyperparams.colsample_bytree,
             # General parameters
             "random_state": self.random_state,
-            "early_stopping_rounds": self.early_stopping_rounds,
+            "early_stopping_rounds": self.hyperparams.early_stopping_rounds,
             "verbosity": self.verbosity,
             "n_jobs": self.n_jobs,
         }
@@ -238,7 +240,7 @@ class LGBMForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
             base_learner=LGBMRegressor,
             quantile_param="alpha",
             hyperparams=lgbm_params,
-            quantiles=[float(q) for q in self.quantiles],
+            quantiles=self.quantiles,
         )
 
     @property

{openstef_models-4.1.1.dev0 → openstef_models-4.2.1}/src/openstef_models/models/forecasting/lgbmlinear_forecaster.py

@@ -111,6 +111,12 @@ class LGBMLinearHyperParams(HyperParams):
         description="Fraction of features used when constructing each tree. Range: (0,1]",
     )
 
+    # Early Stopping
+    early_stopping_rounds: int | None = Field(
+        default=None,
+        description="Training will stop if performance doesn't improve for this many rounds. Requires validation data.",
+    )
+
     @classmethod
     def forecaster_class(cls) -> "type[LGBMLinearForecaster]":
         """Get forecaster class for these hyperparams.
@@ -185,10 +191,6 @@ class LGBMLinearForecaster(Forecaster, ExplainableForecaster, ContributionsMixin
         alias="seed",
         description="Random seed for reproducibility.",
     )
-    early_stopping_rounds: int | None = Field(
-        default=None,
-        description="Training stops if performance doesn't improve for this many rounds.",
-    )
 
     _lgbmlinear_model: MultiQuantileRegressor = PrivateAttr()
 
@@ -230,7 +232,7 @@ class LGBMLinearForecaster(Forecaster, ExplainableForecaster, ContributionsMixin
             "colsample_bytree": self.hyperparams.colsample_bytree,
             # General parameters
             "random_state": self.random_state,
-            "early_stopping_rounds": self.early_stopping_rounds,
+            "early_stopping_rounds": self.hyperparams.early_stopping_rounds,
             "verbosity": self.verbosity,
             "n_jobs": self.n_jobs,
         }
@@ -239,7 +241,7 @@ class LGBMLinearForecaster(Forecaster, ExplainableForecaster, ContributionsMixin
             base_learner=LGBMRegressor,
             quantile_param="alpha",
             hyperparams=lgbmlinear_params,
-            quantiles=[float(q) for q in self.quantiles],
+            quantiles=self.quantiles,
         )
 
     @property

{openstef_models-4.1.1.dev0 → openstef_models-4.2.1}/src/openstef_models/presets/forecasting_workflow.py

@@ -453,7 +453,13 @@ def create_forecasting_workflow(
             horizons=config.horizons,
             hyperparams=config.lgbmlinear_hyperparams,
         )
-        postprocessing = [QuantileSorter()]
+        postprocessing = [
+            QuantileSorter(),
+            ConfidenceIntervalApplicator(
+                quantiles=config.quantiles,
+                add_quantiles_from_std=False,
+            ),
+        ]
     elif config.model == "lgbm":
         preprocessing = [
             *checks,
@@ -468,7 +474,13 @@ def create_forecasting_workflow(
             horizons=config.horizons,
             hyperparams=config.lgbm_hyperparams,
         )
-        postprocessing = [QuantileSorter()]
+        postprocessing = [
+            QuantileSorter(),
+            ConfidenceIntervalApplicator(
+                quantiles=config.quantiles,
+                add_quantiles_from_std=False,
+            ),
+        ]
     elif config.model == "gblinear":
         preprocessing = [
             *checks,
@@ -510,7 +522,12 @@ def create_forecasting_workflow(
             quantiles=config.quantiles,
             horizons=config.horizons,
         )
-        postprocessing = []
+        postprocessing = [
+            ConfidenceIntervalApplicator(
+                quantiles=config.quantiles,
+                add_quantiles_from_std=False,
+            ),
+        ]
     elif config.model == "constant_quantile":
         preprocessing = [
             CompletenessChecker(
@@ -522,7 +539,12 @@ def create_forecasting_workflow(
             quantiles=config.quantiles,
             horizons=config.horizons,
         )
-        postprocessing = []
+        postprocessing = [
+            ConfidenceIntervalApplicator(
+                quantiles=config.quantiles,
+                add_quantiles_from_std=False,
+            ),
+        ]
     elif config.model == "flatliner":
         preprocessing = []
         forecaster = FlatlinerForecaster(

{openstef_models-4.1.1.dev0 → openstef_models-4.2.1}/src/openstef_models/transforms/postprocessing/isotonic_quantile_calibrator.py

@@ -161,7 +161,7 @@ class IsotonicQuantileCalibrator(BaseModel, Transform[ForecastDataset, ForecastD
                 continue  # Skip this quantile
 
             if self.use_local_quantile_estimation:
-                actuals_clean = self._estimate_local_quantiles(predictions_clean, actuals_clean, float(quantile))
+                actuals_clean = self._estimate_local_quantiles(predictions_clean, actuals_clean, quantile)
 
             # Fit isotonic regression
             calibrator = IsotonicRegression(
@@ -184,7 +184,7 @@ class IsotonicQuantileCalibrator(BaseModel, Transform[ForecastDataset, ForecastD
         self._is_fitted = True
 
     def _estimate_local_quantiles(
-        self, predictions: np.ndarray, actuals: np.ndarray, quantile_level: float
+        self, predictions: np.ndarray, actuals: np.ndarray, quantile_level: Quantile
     ) -> np.ndarray:
         """Estimate local quantiles using adaptive windowing.
 

{openstef_models-4.1.1.dev0 → openstef_models-4.2.1}/src/openstef_models/utils/multi_quantile_regressor.py

@@ -13,6 +13,8 @@ import numpy.typing as npt
 import pandas as pd
 from sklearn.base import BaseEstimator, RegressorMixin
 
+from openstef_core.types import Quantile
+
 logger = logging.getLogger(__name__)
 
 ParamType = float | int | str | bool | None
@@ -29,7 +31,7 @@ class MultiQuantileRegressor(BaseEstimator, RegressorMixin):
         self,
         base_learner: type[BaseEstimator],
         quantile_param: str,
-        quantiles: list[float],
+        quantiles: list[Quantile],
         hyperparams: dict[str, ParamType],
     ):
         """Initialize MultiQuantileRegressor.
@@ -82,6 +84,9 @@ class MultiQuantileRegressor(BaseEstimator, RegressorMixin):
         """
         # Pass model-specific eval arguments
         kwargs = {}
+
+        x_array = np.asarray(X)
+
         for model in self._models:
             # Check if early stopping is supported
             # Check that eval_set is supported
@@ -89,21 +94,20 @@ class MultiQuantileRegressor(BaseEstimator, RegressorMixin):
                 model.set_params(early_stopping_rounds=None)
 
             if eval_set is not None and self.learner_eval_sample_weight_param is not None:
+                kwargs["eval_set"] = [
+                    (x_array if eval_x is X else np.asarray(eval_x), eval_y) for eval_x, eval_y in eval_set
+                ]
                 kwargs[self.learner_eval_sample_weight_param] = eval_sample_weight
-
-            if "early_stopping_rounds" in self.hyperparams and self.learner_eval_sample_weight_param is not None:
-                model.set_params(early_stopping_rounds=self.hyperparams["early_stopping_rounds"])
+                if "early_stopping_rounds" in self.hyperparams:
+                    model.set_params(early_stopping_rounds=self.hyperparams["early_stopping_rounds"])
 
             if feature_name:
                 self.model_feature_names = feature_name
             else:
                 self.model_feature_names = []
 
-            if eval_sample_weight is not None and self.learner_eval_sample_weight_param:
-                kwargs[self.learner_eval_sample_weight_param] = eval_sample_weight
-
             model.fit(  # type: ignore
-                X=np.asarray(X),
+                X=x_array,
                 y=y,
                 sample_weight=sample_weight,
                 **kwargs,

{openstef_models-4.1.1.dev0 → openstef_models-4.2.1}/tests/unit/utils/test_multi_quantile_regressor.py

@@ -10,6 +10,7 @@ from sklearn.base import BaseEstimator
 from sklearn.linear_model import QuantileRegressor
 from xgboost import XGBRegressor
 
+from openstef_core.types import Quantile
 from openstef_models.utils.multi_quantile_regressor import MultiQuantileRegressor, ParamType
 
 ParamDict = dict[str, ParamType]
@@ -66,7 +67,7 @@ def baselearner_config(request: pytest.FixtureRequest) -> BaseLearnerConfig:
 
 def test_init_sets_quantiles_and_models(baselearner_config: BaseLearnerConfig):
     # Arrange
-    quantiles = [0.1, 0.5, 0.9]
+    quantiles = [Quantile(0.1), Quantile(0.5), Quantile(0.9)]
 
     # Act
     model = MultiQuantileRegressor(
@@ -83,7 +84,7 @@ def test_init_sets_quantiles_and_models(baselearner_config: BaseLearnerConfig):
 
 def test_fit_and_predict_shape(dataset: tuple[pd.DataFrame, pd.Series], baselearner_config: BaseLearnerConfig):
     # Arrange
-    quantiles = [0.1, 0.5, 0.9]
+    quantiles = [Quantile(0.1), Quantile(0.5), Quantile(0.9)]
     X, y = dataset[0], dataset[1]
     model = MultiQuantileRegressor(
         base_learner=baselearner_config.base_learner,
@@ -102,7 +103,7 @@ def test_fit_and_predict_shape(dataset: tuple[pd.DataFrame, pd.Series], baselear
 
 def test_is_fitted_true_after_fit(dataset: tuple[pd.DataFrame, pd.Series], baselearner_config: BaseLearnerConfig):
     # Arrange
-    quantiles = [0.1, 0.5, 0.9]
+    quantiles = [Quantile(0.1), Quantile(0.5), Quantile(0.9)]
     X, y = dataset[0], dataset[1]
     model = MultiQuantileRegressor(
         base_learner=baselearner_config.base_learner,
@@ -116,3 +117,28 @@ def test_is_fitted_true_after_fit(dataset: tuple[pd.DataFrame, pd.Series], basel
 
     # Assert
     assert model.is_fitted
+
+
+def test_fit_forwards_eval_set_for_early_stopping_lgbm(dataset: tuple[pd.DataFrame, pd.Series]):
+    # Arrange
+    quantiles = [Quantile(0.1), Quantile(0.5), Quantile(0.9)]
+    early_stopping_rounds = 3
+    X, y = dataset
+    y = y.to_numpy()
+    X_train, y_train = X.iloc[:80], y[:80]  # noqa: N806
+    X_val, y_val = X.iloc[80:], y[80:]  # noqa: N806
+    model = MultiQuantileRegressor(
+        base_learner=LGBMRegressor,
+        quantile_param="alpha",
+        quantiles=quantiles,
+        hyperparams={"objective": "quantile", "n_estimators": 10, "early_stopping_rounds": early_stopping_rounds},
+    )
+
+    # Act
+    model.fit(X_train, y_train, eval_set=[(X_train, y_train), (X_val, y_val)])
+
+    # Assert
+    for estimator in model.models:
+        assert isinstance(estimator, LGBMRegressor)
+        assert estimator.get_params()["early_stopping_rounds"] == early_stopping_rounds
+        assert estimator.evals_result_