openstef 3.4.22__tar.gz → 3.4.24__tar.gz

{openstef-3.4.22 → openstef-3.4.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: openstef
-Version: 3.4.22
+Version: 3.4.24
 Summary: Open short term energy forecaster
 Home-page: https://github.com/OpenSTEF/openstef
 Author: Alliander N.V
@@ -128,4 +128,4 @@ Please read [CODE_OF_CONDUCT.md](https://github.com/OpenSTEF/.github/blob/main/C
 
 # Contact
 Please read [SUPPORT.md](https://github.com/OpenSTEF/.github/blob/main/SUPPORT.md) for how to connect and get into contact with the OpenSTEF project
-
+ 

{openstef-3.4.22 → openstef-3.4.24}/README.md

@@ -91,4 +91,4 @@ Please read [CODE_OF_CONDUCT.md](https://github.com/OpenSTEF/.github/blob/main/C
 
 # Contact
 Please read [SUPPORT.md](https://github.com/OpenSTEF/.github/blob/main/SUPPORT.md) for how to connect and get into contact with the OpenSTEF project
-
+ 

{openstef-3.4.22 → openstef-3.4.24}/openstef/data_classes/prediction_job.py

@@ -26,6 +26,7 @@ class PredictionJobDataClass(BaseModel):
         - ``"lgb"``
         - ``"linear"``
         - ``"linear_quantile"``
+        - ``"xgb_multioutput_quantile"``
 
     If unsure what to pick, choose ``"xgb"``.
 

{openstef-3.4.22 → openstef-3.4.24}/openstef/enums.py

@@ -8,6 +8,7 @@ from enum import Enum
 class MLModelType(Enum):
     XGB = "xgb"
     XGB_QUANTILE = "xgb_quantile"
+    XGB_MULTIOUTPUT_QUANTILE = "xgb_multioutput_quantile"
     LGB = "lgb"
     LINEAR = "linear"
     LINEAR_QUANTILE = "linear_quantile"

{openstef-3.4.22 → openstef-3.4.24}/openstef/metrics/metrics.py

@@ -431,3 +431,54 @@ def xgb_quantile_obj(
     hess = np.ones_like(preds)
 
     return grad, hess
+
+
+def arctan_loss(y_true, y_pred, taus, s=0.1):
+    """Compute the arctan pinball loss.
+
+    Note that XGBoost outputs the predictions in a slightly peculiar manner.
+    Suppose we have 100 data points and we predict 10 quantiles. The predictions
+    will be an array of size (1000 x 1). We first resize this to a (100x10) array
+    where each row corresponds to the 10 predicted quantile for a single data
+    point. We then use a for-loop (over the 10 columns) to calculate the gradients
+    and second derivatives. Legibility was chosen over efficiency. This part
+    can be made more efficient.
+
+    Args:
+        y_true: An array containing the true observations.
+        y_pred: An array containing the predicted quantiles.
+        taus: A list containing the true desired coverage of the quantiles.
+        s: A smoothing parameter.
+
+    Returns:
+        grad: An array containing the (negative) gradients with respect to y_pred.
+        hess: An array containing the second derivative with respect to y_pred.
+
+    """
+    size = len(y_true)
+    n_dim = len(taus)  # The number of columns
+    n_rows = size // n_dim
+
+    # Resize the predictions and targets.
+    # Each column corresponds to a quantile, each row to a data point.
+    y_pred = np.reshape(y_pred, (n_rows, n_dim))
+    y_true = np.reshape(y_true, (n_rows, n_dim))
+
+    # Calculate the differences
+    u = y_true - y_pred
+
+    # Calculate the gradient and second derivatives
+    grad = np.zeros_like(y_pred)
+    hess = np.zeros_like(y_pred)
+    z = u / s
+    for i, tau in enumerate(taus):
+        x = 1 + z[:, i] ** 2
+        grad[:, i] = (
+            tau - 0.5 + 1 / np.pi * np.arctan(z[:, i]) + z[:, i] / (np.pi) * x**-1
+        )
+        hess[:, i] = 2 / (np.pi * s) * x ** (-2)
+
+    # Reshape back to the original shape.
+    grad = grad.reshape(size)
+    hess = hess.reshape(size)
+    return -grad / n_dim, hess / n_dim

{openstef-3.4.22 → openstef-3.4.24}/openstef/model/model_creator.py

@@ -15,6 +15,9 @@ from openstef.model.regressors.linear_quantile import LinearQuantileOpenstfRegre
 from openstef.model.regressors.regressor import OpenstfRegressor
 from openstef.model.regressors.xgb import XGBOpenstfRegressor
 from openstef.model.regressors.xgb_quantile import XGBQuantileOpenstfRegressor
+from openstef.model.regressors.xgb_multioutput_quantile import (
+    XGBMultiOutputQuantileOpenstfRegressor,
+)
 from openstef.settings import Settings
 
 structlog.configure(
@@ -87,6 +90,16 @@ valid_model_kwargs = {
         "max_depth",
         "early_stopping_rounds",
     ],
+    MLModelType.XGB_MULTIOUTPUT_QUANTILE: [
+        "quantiles",
+        "gamma",
+        "colsample_bytree",
+        "subsample",
+        "min_child_weight",
+        "max_depth",
+        "early_stopping_rounds",
+        "arctan_smoothing",
+    ],
     MLModelType.LINEAR: [
         "missing_values",
         "imputation_strategy",
@@ -117,6 +130,7 @@ class ModelCreator:
         MLModelType.XGB: XGBOpenstfRegressor,
         MLModelType.LGB: LGBMOpenstfRegressor,
         MLModelType.XGB_QUANTILE: XGBQuantileOpenstfRegressor,
+        MLModelType.XGB_MULTIOUTPUT_QUANTILE: XGBMultiOutputQuantileOpenstfRegressor,
         MLModelType.LINEAR: LinearOpenstfRegressor,
         MLModelType.LINEAR_QUANTILE: LinearQuantileOpenstfRegressor,
         MLModelType.ARIMA: ARIMAOpenstfRegressor,

{openstef-3.4.22 → openstef-3.4.24}/openstef/model/objective.py

@@ -349,6 +349,36 @@ class XGBQuantileRegressorObjective(RegressorObjective):
         )
 
 
+class XGBMultioutputQuantileRegressorObjective(RegressorObjective):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.model_type = MLModelType.XGB_QUANTILE
+
+    def get_params(self, trial: optuna.trial.FrozenTrial) -> dict:
+        """Get parameters for XGB Multioutput Quantile Regressor Objective with objective specific parameters.
+
+        Args: trial
+
+        Returns:
+            Dictionary with hyperparameter name as key and hyperparamer value as value.
+
+        """
+        # Filtered default parameters
+        model_params = super().get_params(trial)
+
+        # XGB specific parameters
+        params = {
+            "gamma": trial.suggest_float("gamma", 1e-8, 1.0),
+            "arctan_smoothing": trial.suggest_float("arctan_smoothing", 0.025, 0.15),
+        }
+        return {**model_params, **params}
+
+    def get_pruning_callback(self, trial: optuna.trial.FrozenTrial):
+        return optuna.integration.XGBoostPruningCallback(
+            trial, observation_key=f"validation_1-{self.eval_metric}"
+        )
+
+
 class LinearRegressorObjective(RegressorObjective):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)

{openstef-3.4.22 → openstef-3.4.24}/openstef/model/objective_creator.py

@@ -12,6 +12,7 @@ from openstef.model.objective import (
     RegressorObjective,
     XGBQuantileRegressorObjective,
     XGBRegressorObjective,
+    XGBMultioutputQuantileRegressorObjective,
 )
 from openstef.model.regressors.custom_regressor import (
     create_custom_objective,
@@ -24,7 +25,9 @@ class ObjectiveCreator:
         MLModelType.XGB: XGBRegressorObjective,
         MLModelType.LGB: LGBRegressorObjective,
         MLModelType.XGB_QUANTILE: XGBQuantileRegressorObjective,
+        MLModelType.XGB_MULTIOUTPUT_QUANTILE: XGBMultioutputQuantileRegressorObjective,
         MLModelType.LINEAR: LinearRegressorObjective,
+        MLModelType.LINEAR_QUANTILE: LinearRegressorObjective,
         MLModelType.ARIMA: ARIMARegressorObjective,
     }
 

{openstef-3.4.22 → openstef-3.4.24}/openstef/model/regressors/linear_quantile.py

@@ -59,6 +59,7 @@ class LinearQuantileOpenstfRegressor(OpenstfRegressor, RegressorMixin):
         - Holiday features (is_christmas, is_*)
         - Lagged features (T-1d, T-*)
         - Point in time features (IsWeekendDay, IsWeekDay, IsSunday, Month, Quarter)
+        - Infeed MFFBAS profiles (E*_I)
 
         Args:
             quantiles: Tuple with desired quantiles, quantile 0.5 is required.
@@ -130,6 +131,9 @@ class LinearQuantileOpenstfRegressor(OpenstfRegressor, RegressorMixin):
             or
             # Ignore lag features
             re.match(r"T-", feature_name) is not None
+            or
+            # Ignore infeed MFFBAS profiles
+            re.match(r"E\d.*_I", feature_name) is not None
         )
 
     def _remove_ignored_features(self, x: pd.DataFrame) -> pd.DataFrame:

openstef-3.4.24/openstef/model/regressors/xgb_multioutput_quantile.py

@@ -0,0 +1,261 @@
+# SPDX-FileCopyrightText: 2017-2023 Contributors to the OpenSTEF project <korte.termijn.prognoses@alliander.com> # noqa E501>
+#
+# SPDX-License-Identifier: MPL-2.0
+from functools import partial
+from typing import Dict, Optional, Sequence, Tuple, Union
+
+import numpy as np
+import pandas as pd
+import sklearn.base
+import xgboost as xgb
+from sklearn.compose import TransformedTargetRegressor
+from sklearn.preprocessing import StandardScaler
+from sklearn.utils.validation import check_array, check_is_fitted, check_X_y
+from xgboost import Booster
+
+import openstef.metrics.metrics as metrics
+from openstef.model.regressors.regressor import OpenstfRegressor
+
+DEFAULT_QUANTILES: tuple[float, ...] = (0.9, 0.5, 0.1)
+
+
+class XGBMultiOutputQuantileOpenstfRegressor(OpenstfRegressor):
+    r"""Model that provides multioutput quantile regression with XGBoost by default using the arctan loss function.
+
+    Arctan loss:
+        Refence: https://github.com/LaurensSluyterman/XGBoost_quantile_regression/tree/master
+        The key idea is to use a smooth approximation of the pinball loss, the arctan
+        pinball loss, that has a relatively large second derivative.
+
+        The approximation is given by:
+        $$L^{(\text{arctan})}_{\tau, s}(u) = (\tau - 0.5 + \frac{\arctan (u/s)}{\pi})u   + \frac{s}{\pi}$$.  # noqa E501
+
+        Some important settings:
+
+        * The parameter in the loss function determines the amount of smoothing. A
+            smaller values gives a closer approximation but also a much smaller second
+            derivative. A larger value gives more conservative quantiles when
+            is larger than 0.5, the quantile becomes larger and vice versa.
+            Values between 0.05 and 0.1 appear to work well. It may be a good idea to
+            optimize this parameter.
+        * Set min-child-weight to zero. The second derivatives can be a lot smaller
+            than 1 and this parameter may prevent any splits.
+        * Use a relatively small max-delta-step. We used a default of 0.5.
+            This prevents excessive steps that could happen due to the relatively
+            small second derivative.
+        * For the same reason, use a slightly lower learning rate of 0.05.
+
+    """
+
+    estimator_: TransformedTargetRegressor
+    quantile_indices_: Dict[float, int]
+
+    @staticmethod
+    def _get_importance_names():
+        return {
+            "gain_importance_name": "total_gain",
+            "weight_importance_name": "weight",
+        }
+
+    def __init__(
+        self,
+        quantiles: tuple[float, ...] = DEFAULT_QUANTILES,
+        gamma: float = 0.0,
+        colsample_bytree: float = 1.0,
+        subsample: float = 1.0,
+        min_child_weight: int = 0,
+        max_depth: int = 6,
+        learning_rate: float = 0.22,
+        alpha: float = 0.0,
+        max_delta_step: int = 0.5,
+        arctan_smoothing: float = 0.055,
+        early_stopping_rounds: Optional[int] = None,
+    ):
+        """Initialize XGBMultiQuantileRegressor.
+
+        Model that provides quantile regression with XGBoost.
+        For each desired quantile an XGBoost model is trained,
+        these can later be used to predict quantiles.
+
+        Args:
+            quantiles: Tuple with desired quantiles, quantile 0.5 is required.
+                For example: (0.1, 0.5, 0.9)
+            gamma: Gamma.
+            colsample_bytree: Colsample by tree.
+            subsample: Subsample.
+            min_child_weight: Minimum child weight.
+            max_depth: Maximum depth.
+            learning_rate: Learning rate.
+            alpha: Alpha.
+            max_delta_step: Maximum delta step.
+            arctan_smoothing: smoothing parameter of the arctan loss function.
+            early_stopping_rounds: Number of rounds to stop training if no improvement
+                is made.
+
+        Raises:
+            ValueError in case quantile 0.5 is not in the requested quantiles.
+
+        """
+        super().__init__()
+        if 0.5 not in quantiles:
+            raise ValueError(
+                "Cannot train quantile model as 0.5 is not in requested quantiles!"
+            )
+
+        self.quantiles = quantiles
+
+        # Set attributes for hyper parameters
+        self.subsample = subsample
+        self.min_child_weight = min_child_weight
+        self.max_depth = max_depth
+        self.gamma = gamma
+        self.alpha = alpha
+        self.max_delta_step = max_delta_step
+        self.colsample_bytree = colsample_bytree
+        self.learning_rate = learning_rate
+        self.early_stopping_rounds = early_stopping_rounds
+        self.arctan_smoothing = arctan_smoothing
+
+        # Get fitting parameters - only those required for xgbooster's
+        xgb_regressor_params = {
+            key: value
+            for key, value in self.get_params().items()
+            if key in xgb.XGBRegressor().get_params().keys()
+        }
+
+        # Define the model
+        objective = partial(
+            metrics.arctan_loss, taus=self.quantiles, s=arctan_smoothing
+        )
+        xgb_model: xgb.XGBRegressor = xgb.XGBRegressor(
+            objective=objective,
+            base_score=0,
+            multi_strategy="one_output_per_tree",
+            **xgb_regressor_params,
+        )
+        self.estimator_ = TransformedTargetRegressor(
+            regressor=xgb_model, transformer=StandardScaler()
+        )
+
+        # Set quantile indices to remap multioutput predictions
+        self.quantile_indices_ = {
+            quantile: i for i, quantile in enumerate(self.quantiles)
+        }
+
+    def fit(
+        self,
+        x: np.array,
+        y: np.array,
+        eval_set: Optional[Sequence[Tuple[np.array, np.array]]] = None,
+        verbose: Optional[Union[bool, int]] = 0,
+        **kwargs
+    ) -> OpenstfRegressor:
+        """Fits xgb quantile model.
+
+        Args:
+            x: Feature matrix.
+            y: Labels.
+            eval_set: Evaluation set to monitor training performance.
+            verbose: Verbosity level (disabled by default).
+
+        Returns:
+            Fitted XGBQuantile model.
+
+        """
+        if isinstance(y, pd.Series):
+            y = y.to_numpy()
+
+        if not isinstance(x, pd.DataFrame):
+            x = pd.DataFrame(np.asarray(x))
+
+        # Check/validate input
+        check_X_y(x, y, force_all_finite="allow-nan")
+
+        # Prepare inputs
+        y_multioutput = replicate_for_multioutput(y, len(self.quantiles))
+
+        # Define watchlist if eval_set is defined
+        eval_set_multioutput = []
+        if eval_set:
+            for x_eval, y_eval in eval_set:
+                if isinstance(y_eval, pd.Series):
+                    y_eval = y_eval.to_numpy()
+
+                y_eval_multioutput = replicate_for_multioutput(
+                    y=y_eval, num_quantiles=len(self.quantiles)
+                )
+                eval_set_multioutput.append((x_eval, y_eval_multioutput))
+
+            eval_set_multioutput.append((x, y_multioutput))
+
+        self.estimator_.fit(
+            X=x.copy(deep=True),
+            y=y_multioutput,
+            eval_set=eval_set_multioutput,
+            verbose=verbose,
+        )
+
+        # Update state of the estimator
+        self.feature_importances_ = self.estimator_.regressor_.feature_importances_
+        self.is_fitted_ = True
+
+        return self
+
+    def predict(self, x: np.array, quantile: float = 0.5) -> np.array:
+        """Makes a prediction for a desired quantile.
+
+        Args:
+            x: Feature matrix.
+            quantile: Quantile for which a prediciton is desired,
+                note that only quantile are available for which a model is trained,
+                and that this is a quantile-model specific keyword.
+
+        Returns:
+            Prediction
+
+        Raises:
+            ValueError in case no model is trained for the requested quantile.
+
+        """
+        # Check if model is trained for this quantile
+        if quantile not in self.quantiles:
+            raise ValueError("No model trained for requested quantile!")
+
+        # Check/validate input
+        check_array(x, force_all_finite="allow-nan")
+        check_is_fitted(self)
+
+        # best_iteration is only available if early stopping was used during training
+        prediction: np.array
+        if hasattr(self.estimator_, "best_iteration"):
+            prediction = self.estimator_.predict(
+                X=x,
+                iteration_range=(0, self.estimator_.best_iteration + 1),
+            )
+        else:
+            prediction = self.estimator_.predict(X=x)
+
+        quantile_index = self.quantile_indices_[quantile]
+        return prediction[:, quantile_index]
+
+    @property
+    def feature_names(self):
+        return self.estimator_.feature_names_in_
+
+    @property
+    def can_predict_quantiles(self):
+        return True
+
+
+def replicate_for_multioutput(y: np.array, num_quantiles: int) -> np.array:
+    """Replicates a 1D array to a 2D array for multioutput regression.
+
+    Args:
+        y: 1D array.
+        num_quantiles: Number of columns in the output array.
+
+    Returns:
+        2D array with shape (len(y), num_quantiles)
+
+    """
+    return np.repeat(y[:, None], num_quantiles, axis=1)

{openstef-3.4.22 → openstef-3.4.24}/openstef.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: openstef
-Version: 3.4.22
+Version: 3.4.24
 Summary: Open short term energy forecaster
 Home-page: https://github.com/OpenSTEF/openstef
 Author: Alliander N.V
@@ -128,4 +128,4 @@ Please read [CODE_OF_CONDUCT.md](https://github.com/OpenSTEF/.github/blob/main/C
 
 # Contact
 Please read [SUPPORT.md](https://github.com/OpenSTEF/.github/blob/main/SUPPORT.md) for how to connect and get into contact with the OpenSTEF project
-
+ 

{openstef-3.4.22 → openstef-3.4.24}/openstef.egg-info/SOURCES.txt

@@ -76,6 +76,7 @@ openstef/model/regressors/linear.py
 openstef/model/regressors/linear_quantile.py
 openstef/model/regressors/regressor.py
 openstef/model/regressors/xgb.py
+openstef/model/regressors/xgb_multioutput_quantile.py
 openstef/model/regressors/xgb_quantile.py
 openstef/model_selection/__init__.py
 openstef/model_selection/model_selection.py

{openstef-3.4.22 → openstef-3.4.24}/setup.py

@@ -29,7 +29,7 @@ def read_long_description_from_readme():
 
 setup(
     name="openstef",
-    version="3.4.22",
+    version="3.4.24",
     packages=find_packages(include=["openstef", "openstef.*"]),
     description="Open short term energy forecaster",
     long_description=read_long_description_from_readme(),