openstef-models 4.2.2__tar.gz → 4.3.0__tar.gz

{openstef_models-4.2.2 → openstef_models-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: openstef-models
-Version: 4.2.2
+Version: 4.3.0
 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.2.2 → openstef_models-4.3.0}/pyproject.toml

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

{openstef_models-4.2.2 → openstef_models-4.3.0}/src/openstef_models/integrations/mlflow/mlflow_storage.py

@@ -22,7 +22,7 @@ from urllib.parse import urlparse
 from mlflow import MlflowClient
 from mlflow.entities import Metric, Param, Run
 from mlflow.exceptions import MlflowException
-from pydantic import Field, PrivateAttr
+from pydantic import ConfigDict, Field, PrivateAttr
 
 from openstef_core.base_model import BaseConfig
 from openstef_core.exceptions import ModelNotFoundError
@@ -31,7 +31,7 @@ from openstef_models.integrations.joblib import JoblibModelSerializer
 from openstef_models.mixins import ModelIdentifier, ModelSerializer
 
 
-def normalize_tracking_uri(uri: str) -> str:
+def normalize_tracking_uri(uri: str, exceptions: Sequence[str] = []) -> str:
     r"""Normalize a tracking URI to a file:/// URI when it refers to a local path.
 
     MLflow's model registry rejects bare Windows paths (e.g. ``D:\mlflow``) because
@@ -44,10 +44,13 @@ def normalize_tracking_uri(uri: str) -> str:
 
     Args:
         uri: Raw tracking URI string, may be a path or a proper URI.
+        exceptions: List of URI to treat as urls even if they have no scheme
 
     Returns:
         A ``file:///`` URI for local paths, or the original URI for remote schemes.
     """
+    if uri in exceptions:
+        return uri
     scheme = urlparse(uri).scheme
     # Empty scheme → relative/absolute POSIX path.
     # Single-letter scheme → Windows drive letter (e.g. "D" from "D:\\...").
@@ -63,9 +66,33 @@ class MLFlowStorage(BaseConfig):
     Handles creation, storage, and retrieval of MLflow runs including models,
     training data, metrics, and hyperparameters. Organizes artifacts locally
     before uploading to MLflow tracking server.
+
+    ``tracking_uri`` configures the Tracking backend that stores experiments and
+    runs. ``registry_uri`` optionally configures a separate Model Registry
+    backend; if it is omitted, MLflow uses the registry associated with the
+    tracking backend. ``artifact_location`` configures the artifact root for
+    experiments created by this instance.
+
+    Typical configurations:
+
+    tracking_uri="sqlite:///mlflow.db", # Local SQLite tracking backend with separate local artifacts
+    tracking_uri="https://mlflow.example.com", # Remote MLflow Tracking Server with S3 artifacts
+    tracking_uri="databricks", # Databricks MLflow Tracking Server with DBFS artifacts
+
+    A caller may provide ``client`` to use an already configured
+    :class:`mlflow.MlflowClient`. When supplied, it takes precedence over
+    ``tracking_uri`` and ``registry_uri`` and is excluded from serialized model
+    configuration.
     """
 
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
     tracking_uri: str = Field(default="./mlflow", description="MLflow tracking server URI.")
+    registry_uri: str | None = Field(default=None, description="MLflow tracking server URI.")
+
+    # Excluded from model_dump(), JSON serialization, and config persistence.
+    client: MlflowClient | None = Field(default=None, exclude=True, repr=False)
+
     local_artifacts_path: Path = Field(
         default=Path("./mlflow_artifacts_local"), description="Local path for storing MLflow artifacts before upload."
     )
@@ -86,6 +113,11 @@ class MLFlowStorage(BaseConfig):
 
     model_serializer: ModelSerializer = Field(default_factory=JoblibModelSerializer)
 
+    uri_exceptions: Sequence[str] = Field(
+        default=["databricks"],
+        description="List of URI treat as urls even if they have no scheme",
+    )
+
     _client: MlflowClient = PrivateAttr()
     _logger: logging.Logger = PrivateAttr(default=logging.getLogger(__name__))
 
@@ -95,8 +127,17 @@ class MLFlowStorage(BaseConfig):
             # Suppress MLflow's stdout messages (emoji URLs)
             os.environ.setdefault("MLFLOW_SUPPRESS_PRINTING_URL_TO_STDOUT", "true")
             os.environ.setdefault("MLFLOW_ENABLE_ARTIFACTS_PROGRESS_BAR", "false")
+
+        if self.client is not None:
+            self._client = self.client
+            return
+
         self.tracking_uri = normalize_tracking_uri(self.tracking_uri)
-        self._client = MlflowClient(tracking_uri=self.tracking_uri)
+        self.registry_uri = normalize_tracking_uri(self.registry_uri) if self.registry_uri else None
+        self._client = MlflowClient(
+            tracking_uri=self.tracking_uri,
+            registry_uri=self.registry_uri,
+        )
 
     def create_run(
         self,

{openstef_models-4.2.2 → openstef_models-4.3.0}/src/openstef_models/models/forecasting/median_forecaster.py

@@ -200,7 +200,10 @@ class MedianForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
         lag_df = input_data.reindex(new_index, fill_value=np.nan)[self._feature_names]
 
         # Convert the lag DataFrame to NumPy arrays for faster processing.
-        lag_array = lag_df.to_numpy()
+        # Copy explicitly: pandas Copy-on-Write may hand back a read-only view of the
+        # DataFrame's underlying block, but the autoregressive loop below fills the
+        # array in place (via _fill_diagonal_with_median), so it must own a writable copy.
+        lag_array = lag_df.to_numpy(copy=True)
         # Initialize the prediction array with NaNs.
         prediction = np.full(lag_array.shape[0], np.nan)
 

{openstef_models-4.2.2 → openstef_models-4.3.0}/src/openstef_models/presets/forecasting_workflow.py

@@ -233,6 +233,14 @@ class ForecastingWorkflowConfig(BaseConfig):  # PredictionJob
         description="Feature selection for which features to replace out-of-range values with NaN. "
         "Defaults to no features (disabled).",
     )
+    outlier_strictness_n_std: float = Field(
+        default=2.0,
+        description=(
+            "Number of standard deviations for outlier detection (lower = stricter bounds). "
+            "Only used when nan_on_outlier_features is enabled."
+        ),
+        gt=0,
+    )
     max_day_lags: int = Field(
         default=14,
         description="Maximum number of days to look back for day-based lags. "
@@ -412,7 +420,14 @@ def create_forecasting_workflow(
     if config.model == "xgboost":
         nan_outlier_handlers = [
             *(
-                [OutlierHandler(mode="standard", selection=config.nan_on_outlier_features, outlier_action="nan")]
+                [
+                    OutlierHandler(
+                        mode="standard",
+                        selection=config.nan_on_outlier_features,
+                        outlier_action="nan",
+                        n_std=config.outlier_strictness_n_std,
+                    )
+                ]
                 if config.nan_on_outlier_features != FeatureSelection.NONE
                 else []
             ),

{openstef_models-4.2.2 → openstef_models-4.3.0}/src/openstef_models/transforms/postprocessing/__init__.py

@@ -10,7 +10,13 @@ operate on ForecastDataset objects after the core prediction step.
 """
 
 from openstef_models.transforms.postprocessing.confidence_interval_applicator import ConfidenceIntervalApplicator
+from openstef_models.transforms.postprocessing.conformalized_quantile_calibrator import ConformalizedQuantileCalibrator
 from openstef_models.transforms.postprocessing.isotonic_quantile_calibrator import IsotonicQuantileCalibrator
 from openstef_models.transforms.postprocessing.quantile_sorter import QuantileSorter
 
-__all__ = ["ConfidenceIntervalApplicator", "IsotonicQuantileCalibrator", "QuantileSorter"]
+__all__ = [
+    "ConfidenceIntervalApplicator",
+    "ConformalizedQuantileCalibrator",
+    "IsotonicQuantileCalibrator",
+    "QuantileSorter",
+]

openstef_models-4.3.0/src/openstef_models/transforms/postprocessing/conformalized_quantile_calibrator.py

@@ -0,0 +1,115 @@
+# SPDX-FileCopyrightText: 2026 Contributors to the OpenSTEF project <openstef@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Asymmetric conformal quantile calibration without external dependencies."""
+
+import logging
+from typing import override
+
+import numpy as np
+from pydantic import BaseModel, Field, PrivateAttr
+
+from openstef_core.datasets import ForecastDataset
+from openstef_core.exceptions import NotFittedError
+from openstef_core.mixins import Transform
+from openstef_core.types import Quantile
+
+MEDIAN_QUANTILE = Quantile(0.5)
+
+
+def _conformal_quantile(scores: np.ndarray, level: float) -> float:
+    """Return the finite-sample conformal quantile of one-sided scores."""
+    n_samples = scores.size
+    if n_samples == 0:
+        return 0.0
+    adjusted_level = min(level * (n_samples + 1) / n_samples, 1.0)
+    return float(np.quantile(scores, adjusted_level, method="higher"))
+
+
+class ConformalizedQuantileCalibrator(BaseModel, Transform[ForecastDataset, ForecastDataset]):
+    """Apply asymmetric split-conformal corrections to forecast quantiles.
+
+    Lower quantiles are corrected using lower-tail scores and upper quantiles
+    using upper-tail scores. The median is left unchanged by default.
+
+    Args:
+        quantiles: Quantiles to calibrate. If None, all input quantiles are used.
+        conformalize_median: Whether to apply the upper-tail correction to P50.
+        min_calibration_samples: Minimum number of valid calibration pairs required
+            before fitting a correction for a quantile. Quantiles with fewer valid
+            pairs are left unchanged; if all quantiles are skipped, fitting becomes
+            a no-op calibrator.
+    """
+
+    quantiles: list[Quantile] | None = Field(default=None)
+    conformalize_median: bool = Field(default=False)
+    min_calibration_samples: int = Field(default=100, ge=1)
+
+    _corrections: dict[str, float] = PrivateAttr(default_factory=dict)
+    _is_fitted: bool = PrivateAttr(default=False)
+    _logger: logging.Logger = PrivateAttr(default=logging.getLogger(__name__))
+
+    @property
+    @override
+    def is_fitted(self) -> bool:
+        """Return whether calibration corrections have been fitted."""
+        return self._is_fitted
+
+    @override
+    def fit(self, data: ForecastDataset) -> None:
+        """Estimate one-sided conformal corrections from forecast errors."""
+        if data.target_series is None:
+            raise ValueError("Input data must contain target series for calibration.")
+
+        quantiles_to_fit = self.quantiles if self.quantiles is not None else data.quantiles
+        if not quantiles_to_fit:
+            raise ValueError("No quantiles found to calibrate.")
+
+        self._is_fitted = False
+        actuals = data.target_series.to_numpy()
+        self._corrections = {}
+
+        for quantile in quantiles_to_fit:
+            column = quantile.format()
+            if column not in data.data.columns:
+                continue
+            if quantile == MEDIAN_QUANTILE and not self.conformalize_median:
+                continue
+
+            predictions = data.data[column].to_numpy()
+            valid = ~(np.isnan(predictions) | np.isnan(actuals))
+            predictions_valid = predictions[valid]
+            actuals_valid = actuals[valid]
+            if predictions_valid.size < self.min_calibration_samples:
+                self._logger.warning(
+                    "Skipping calibration for quantile %s: not enough data points (found %d, require %d).",
+                    column,
+                    predictions_valid.size,
+                    self.min_calibration_samples,
+                )
+                continue
+
+            if quantile < MEDIAN_QUANTILE:
+                scores = predictions_valid - actuals_valid
+                self._corrections[column] = -_conformal_quantile(scores, level=1.0 - quantile)
+            else:
+                scores = actuals_valid - predictions_valid
+                self._corrections[column] = _conformal_quantile(scores, level=quantile)
+
+        self._is_fitted = True
+
+    @override
+    def transform(self, data: ForecastDataset) -> ForecastDataset:
+        """Apply fitted corrections without changing quantile ordering."""
+        if not self._is_fitted:
+            raise NotFittedError(self.__class__.__name__)
+
+        predictions = data.data.copy(deep=False)
+        for column, correction in self._corrections.items():
+            if column in predictions.columns:
+                predictions[column] = predictions[column] + correction
+        return data._copy_with_data(data=predictions)  # noqa: SLF001 - safe transform copy
+
+
+__all__ = ["ConformalizedQuantileCalibrator"]

{openstef_models-4.2.2 → openstef_models-4.3.0}/src/openstef_models/utils/data_split.py

@@ -201,7 +201,7 @@ def _get_extreme_days(
         raise TypeError("target_series must have a DatetimeIndex.")
 
     # Compute daily min and max once
-    daily_agg: pd.DataFrame = target_series.resample("1D").agg(["min", "max"])  # type: ignore
+    daily_agg: pd.DataFrame = target_series.resample("1D").agg(["min", "max"])
     n_days = len(daily_agg)
     n_extremes = max(int(fraction * n_days), 2)
 

{openstef_models-4.2.2 → openstef_models-4.3.0}/tests/unit/integrations/mlflow/test_mlflow_storage.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, cast
 
 import pytest
+from mlflow import MlflowClient
 
 from openstef_core.mixins import HyperParams, Stateful
 from openstef_models.integrations.mlflow import MLFlowStorage
@@ -49,6 +50,21 @@ def model_id() -> str:
     return "test_model_123"
 
 
+def test_construct_from_mlflow(tmp_path: Path, model_id: str):
+    """Test that experiment_name_prefix is prepended to experiment names."""
+    # Arrange
+    mlflow_client = MlflowClient(tracking_uri=f"sqlite:///{tmp_path / 'mlflow.db'}")
+
+    # Act
+    storage = MLFlowStorage(
+        tracking_uri=f"sqlite:///{tmp_path / 'mlflow.db'}",
+        client=mlflow_client,
+    )
+
+    # Assert
+    assert storage._client is mlflow_client
+
+
 def test_create_run(storage: MLFlowStorage, model_id: str):
     """Test that create_run converts HyperParams to MLflow parameters."""
     # Arrange
@@ -194,12 +210,15 @@ def test_search_run__returns_matching_run(storage: MLFlowStorage, model_id: str)
         pytest.param("https://mlflow.example.com:5000", "https://mlflow.example.com:5000", id="https-port"),
         pytest.param("sqlite:///mlflow.db", "sqlite:///mlflow.db", id="sqlite"),
         pytest.param("postgresql://user:pass@host/db", "postgresql://user:pass@host/db", id="postgresql"),
+        pytest.param("databricks", "databricks", id="databricks"),
     ],
 )
 def test_normalize_tracking_uri(uri: str, expected: str):
     """Local paths become file:/// URIs; remote/database URIs pass through unchanged."""
     # Act
-    result = normalize_tracking_uri(uri)
+    result = normalize_tracking_uri(
+        uri, exceptions=["databricks"]
+    )  # databricks is a special case that should not be normalized
 
     # Assert
     if expected == "file:///":

{openstef_models-4.2.2 → openstef_models-4.3.0}/tests/unit/models/forecasting/conftest.py

@@ -30,7 +30,7 @@ def sample_forecast_input_dataset() -> ForecastInputDataset:
                 "feature2": feature_2,
                 "feature3": feature_3,
             },
-            index=pd.date_range(start=start_date, periods=num_samples, freq="1d"),
+            index=pd.date_range(start=start_date, periods=num_samples, freq="1D"),
         ),
         sample_interval=timedelta(days=1),
         target_column="load",

{openstef_models-4.2.2 → openstef_models-4.3.0}/tests/unit/models/forecasting/test_median_forecaster.py

@@ -158,7 +158,12 @@ def test_median_handles_all_missing_data():
             {
                 "quantile_P50": [],
             },
-            index=pd.DatetimeIndex([], freq="h"),
+            # Slice `index` rather than building a bare `DatetimeIndex([], freq="h")` so the
+            # (empty) expected index shares its dtype resolution with the one produced by the
+            # real prediction pipeline (pandas infers datetime64 resolution from context, and
+            # an index with no data to infer from does not necessarily match one derived from
+            # actual timestamps).
+            index=index[:0],
         ),
         sample_interval=training_input_data.sample_interval,
         forecast_start=training_input_data.forecast_start,

{openstef_models-4.2.2 → openstef_models-4.3.0}/tests/unit/transforms/general/test_dimensionality_reducer.py

@@ -33,7 +33,7 @@ def sample_forecast_input_dataset() -> TimeSeriesDataset:
                 "feature2": feature_2,
                 "feature3": feature_3,
             },
-            index=pd.date_range(start=start_date, periods=num_samples, freq="1d"),
+            index=pd.date_range(start=start_date, periods=num_samples, freq="1D"),
         ),
         sample_interval=timedelta(days=1),
     )

openstef_models-4.3.0/tests/unit/transforms/postprocessing/test_conformalized_quantile_calibrator.py

@@ -0,0 +1,141 @@
+# SPDX-FileCopyrightText: 2026 Contributors to the OpenSTEF project <openstef@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from openstef_core.datasets import ForecastDataset
+from openstef_core.types import Quantile
+from openstef_models.transforms.postprocessing import ConformalizedQuantileCalibrator
+
+
+def _dataset(predictions: np.ndarray, actuals: np.ndarray) -> ForecastDataset:
+    """Build a forecast dataset with P10, P50, and P90 columns."""
+    return ForecastDataset(
+        data=pd.DataFrame(
+            {
+                "quantile_P10": predictions[:, 0],
+                "quantile_P50": predictions[:, 1],
+                "quantile_P90": predictions[:, 2],
+                "load": actuals,
+            },
+            index=pd.date_range("2025-01-01", periods=len(actuals), freq="h"),
+        )
+    )
+
+
+def test_conformalized_calibrator_applies_reference_tail_corrections() -> None:
+    """Test asymmetric lower and upper corrections while preserving the median."""
+    predictions = np.column_stack([np.zeros(100), np.full(100, 5.0), np.full(100, 10.0)])
+    actuals = np.concatenate([np.full(90, 1.0), np.full(10, 20.0)])
+    calibration = _dataset(predictions, actuals)
+    forecast = _dataset(predictions[:2], np.full(2, 5.0))
+
+    calibrator = ConformalizedQuantileCalibrator(quantiles=[Quantile(0.1), Quantile(0.5), Quantile(0.9)])
+    calibrator.fit(calibration)
+    result = calibrator.transform(forecast)
+
+    np.testing.assert_allclose(result.data["quantile_P10"], [1.0, 1.0])
+    np.testing.assert_allclose(result.data["quantile_P50"], [5.0, 5.0])
+    np.testing.assert_allclose(result.data["quantile_P90"], [20.0, 20.0])
+
+
+def test_conformalized_calibrator_can_calibrate_the_median_when_enabled() -> None:
+    """Test that median calibration is explicitly opt-in."""
+    predictions = np.column_stack([np.zeros(100), np.zeros(100), np.full(100, 10.0)])
+    actuals = np.full(100, 5.0)
+    calibration = _dataset(predictions, actuals)
+    forecast = _dataset(predictions[:1], np.full(1, 5.0))
+
+    calibrator = ConformalizedQuantileCalibrator(
+        quantiles=[Quantile(0.1), Quantile(0.5), Quantile(0.9)],
+        conformalize_median=True,
+    )
+    calibrator.fit(calibration)
+    result = calibrator.transform(forecast)
+
+    np.testing.assert_allclose(result.data["quantile_P50"], [5.0])
+
+
+def test_conformalized_calibrator_skips_short_calibration_windows() -> None:
+    """Test that too few calibration samples leave forecasts unchanged."""
+    predictions = np.column_stack([np.zeros(2), np.full(2, 5.0), np.full(2, 10.0)])
+    actuals = np.full(2, 20.0)
+    calibration = _dataset(predictions, actuals)
+    forecast = _dataset(predictions[:1], np.full(1, 5.0))
+
+    calibrator = ConformalizedQuantileCalibrator(
+        quantiles=[Quantile(0.1), Quantile(0.5), Quantile(0.9)],
+        min_calibration_samples=3,
+    )
+    calibrator.fit(calibration)
+    result = calibrator.transform(forecast)
+
+    np.testing.assert_allclose(result.data["quantile_P10"], [0.0])
+    np.testing.assert_allclose(result.data["quantile_P90"], [10.0])
+
+
+def test_conformalized_calibrator_skips_only_sparse_quantiles(caplog: pytest.LogCaptureFixture) -> None:
+    """Test that sparse quantiles are skipped while sufficiently populated ones calibrate."""
+    predictions = np.column_stack(
+        [
+            np.concatenate([np.zeros(100), [np.nan]]),
+            np.full(101, 5.0),
+            np.full(101, 10.0),
+        ]
+    )
+    actuals = np.full(101, 20.0)
+    calibration = _dataset(predictions, actuals)
+    forecast = _dataset(np.array([[0.0, 5.0, 10.0]]), np.array([5.0]))
+
+    calibrator = ConformalizedQuantileCalibrator(
+        quantiles=[Quantile(0.1), Quantile(0.5), Quantile(0.9)],
+        min_calibration_samples=101,
+    )
+    calibrator.fit(calibration)
+    result = calibrator.transform(forecast)
+
+    np.testing.assert_allclose(result.data["quantile_P10"], [0.0])
+    np.testing.assert_allclose(result.data["quantile_P90"], [20.0])
+    assert "Skipping calibration for quantile quantile_P10" in caplog.text
+
+
+def test_conformalized_calibrator_skips_quantiles_missing_from_data() -> None:
+    """Test that configured quantiles absent from the data are skipped."""
+    calibration = ForecastDataset(
+        data=pd.DataFrame(
+            {
+                "quantile_P90": np.full(2, 10.0),
+                "load": np.full(2, 20.0),
+            },
+            index=pd.date_range("2025-01-01", periods=2, freq="h"),
+        )
+    )
+    calibrator = ConformalizedQuantileCalibrator(
+        quantiles=[Quantile(0.1), Quantile(0.9)],
+        min_calibration_samples=1,
+    )
+
+    calibrator.fit(calibration)
+    result = calibrator.transform(calibration)
+
+    np.testing.assert_allclose(result.data["quantile_P90"], [20.0, 20.0])
+
+
+def test_conformalized_calibrator_does_not_sort_quantiles() -> None:
+    """Test that ordering remains the responsibility of a downstream sorter."""
+    predictions = np.column_stack([np.full(2, 10.0), np.zeros(2), np.full(2, 5.0)])
+    actuals = np.full(2, 5.0)
+    calibration = _dataset(predictions, actuals)
+    forecast = _dataset(predictions[:1], np.full(1, 5.0))
+
+    calibrator = ConformalizedQuantileCalibrator(
+        quantiles=[Quantile(0.1), Quantile(0.5), Quantile(0.9)],
+        min_calibration_samples=1,
+    )
+    calibrator.fit(calibration)
+    result = calibrator.transform(forecast)
+
+    np.testing.assert_allclose(result.data.filter(like="quantile_").to_numpy(), [[5.0, 0.0, 5.0]])