openstef-core 4.0.1__tar.gz → 4.1.1.dev0__tar.gz

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/.gitignore

@@ -35,10 +35,6 @@ MANIFEST
 # Ruff
 .ruff_cache/
 
-# Pyright
-.pyright/
-# pyright-report/
-
 # Test, coverage, tox
 .pytest_cache/
 .coverage
@@ -69,6 +65,8 @@ docs/_build/
 docs/source/api/generated/
 docs/source/tutorials/
 docs/source/benchmarks/
+# Community health files materialized from OpenSTEF/.github at build time
+docs/source/contribute/_community/
 docs/source/user_guide/**/quick_start_tutorial.py
 docs/source/user_guide/**/feature_engineering_tutorial.py
 docs/source/user_guide/**/datasets_tutorial.py
@@ -135,6 +133,9 @@ benchmark_results*/
 # Local dataset files
 liander_dataset/
 
+# Deployment example run artifacts (MLflow store, forecasts, dataset, Celery/Airflow state)
+openstef_deployment_runs/
+
 # Mlflow
 /mlflow
 /mlflow_artifacts_local

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openstef-core
-Version: 4.0.1
+Version: 4.1.1.dev0
 Summary: Core functionality for OpenSTEF, a framework for short-term energy forecasting.
 Project-URL: Documentation, https://openstef.github.io/openstef/index.html
 Project-URL: Homepage, https://lfenergy.org/projects/openstef/

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/pyproject.toml

@@ -1,15 +1,13 @@
 # SPDX-FileCopyrightText: 2025 Contributors to the OpenSTEF project <openstef@lfenergy.org>
 #
 # SPDX-License-Identifier: MPL-2.0
-
 [build-system]
 build-backend = "hatchling.build"
-
 requires = [ "hatchling" ]
 
 [project]
 name = "openstef-core"
-version = "4.0.1"
+version = "4.1.1.dev0"
 description = "Core functionality for OpenSTEF, a framework for short-term energy forecasting."
 readme = "README.md"
 keywords = [ "energy", "forecasting", "machinelearning" ]
@@ -26,24 +24,22 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
 ]
-
 dependencies = [
   "joblib>=1,<2",
   "numpy>=2.3.2,<3",
+  # Held at <3 pending the pandas 3.0 Copy-on-Write migration (see migration issue).
   "pandas>=2.3.1,<3",
   "pyarrow>=21",
   "pydantic>=2.12.4,<3",
   "pydantic-extra-types>=2.10.5,<3",
 ]
-
 optional-dependencies.benchmark = [
   "huggingface-hub>=1.2.2",
 ]
-
 urls.Documentation = "https://openstef.github.io/openstef/index.html"
 urls.Homepage = "https://lfenergy.org/projects/openstef/"
 urls.Issues = "https://github.com/OpenSTEF/openstef/issues"
 urls.Repository = "https://github.com/OpenSTEF/openstef"
 
-[tool.hatch.build.targets.wheel]
-packages = [ "src/openstef_core" ]
+[tool.hatch]
+build.targets.wheel.packages = [ "src/openstef_core" ]

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/base_model.py

@@ -11,7 +11,7 @@ operate on arbitrary config instances or Pydantic models / adapters.
 """
 
 from pathlib import Path
-from typing import Annotated, Any, Self
+from typing import Annotated, Any, Self, override
 
 import yaml
 from pydantic import BaseModel as PydanticBaseModel
@@ -112,6 +112,7 @@ def read_yaml_config[T: BaseConfig, U](path: Path, class_type: type[T] | TypeAda
 class PydanticStringPrimitive:
     """Base class for Pydantic-compatible types with string serialization."""
 
+    @override
     def __str__(self) -> str:
         """Convert to string representation."""
         raise NotImplementedError("Subclasses must implement __str__")
@@ -158,7 +159,7 @@ class PydanticStringPrimitive:
         )
 
     @classmethod
-    def __get_pydantic_json_schema__(  # noqa: PLW3201
+    def __get_pydantic_json_schema__(
         cls,
         _schema: core_schema.CoreSchema,
         handler: GetJsonSchemaHandler,
@@ -172,6 +173,7 @@ class PydanticStringPrimitive:
         """
         return {"type": "string"}
 
+    @override
     def __eq__(self, other: object) -> bool:
         """Check equality based on string representation.
 
@@ -182,6 +184,7 @@ class PydanticStringPrimitive:
             return NotImplemented
         return str(self) == str(other)
 
+    @override
     def __hash__(self) -> int:
         """Return hash based on string representation."""
         return hash(str(self))

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/datasets/timeseries_dataset.py

@@ -33,7 +33,7 @@ from openstef_core.utils.pandas import unsafe_sorted_range_slice_idxs
 _logger = logging.getLogger(__name__)
 
 
-class TimeSeriesDataset(TimeSeriesMixin, DatasetMixin):  # noqa: PLR0904 - important utility class, allow too many public methods
+class TimeSeriesDataset(TimeSeriesMixin, DatasetMixin):
     """A time series dataset with regular sampling intervals and optional versioning.
 
     This class represents time series data with a consistent sampling interval
@@ -304,7 +304,7 @@ class TimeSeriesDataset(TimeSeriesMixin, DatasetMixin):  # noqa: PLR0904 - impor
         Returns:
             New dataset containing only rows with timestamps in the mask.
         """
-        data_filtered = self.data.loc[self.index.isin(mask)]  # pyright: ignore[reportUnknownMemberType]
+        data_filtered = self.data.loc[self.index.isin(mask)]
 
         return self._copy_with_data(data=data_filtered)
 
@@ -320,7 +320,7 @@ class TimeSeriesDataset(TimeSeriesMixin, DatasetMixin):  # noqa: PLR0904 - impor
         if self.horizons is None:
             return self
 
-        data_selected = self.data[self.lead_time_series == horizon.value]
+        data_selected = cast(pd.DataFrame, self.data[self.lead_time_series == horizon.value])
         return self._copy_with_data(data=data_selected)
 
     def to_pandas(self) -> pd.DataFrame:
@@ -395,7 +395,7 @@ class TimeSeriesDataset(TimeSeriesMixin, DatasetMixin):  # noqa: PLR0904 - impor
         available_at_column: str = "available_at",
         horizon_column: str = "horizon",
     ) -> Self:
-        df = pd.read_parquet(path=path)  # pyright: ignore[reportUnknownMemberType]
+        df = pd.read_parquet(path=path)
         if not isinstance(df.index, pd.DatetimeIndex):
             if timestamp_column not in df.columns:
                 raise TimeSeriesValidationError(
@@ -512,8 +512,8 @@ def validate_horizons_present(dataset: TimeSeriesDataset, horizons: list[LeadTim
     if dataset.horizons is None and len(horizons) == 1:
         return  # Non-versioned dataset can satisfy single-horizon requests
 
-    required_horizons = set(horizons or [])
-    missing_horizons = [h for h in horizons if h not in required_horizons]
+    available_horizons = set(dataset.horizons or [])
+    missing_horizons = [h for h in horizons if h not in available_horizons]
     if missing_horizons:
         raise TimeSeriesValidationError("Missing forecast horizons: " + ", ".join(map(str, missing_horizons)))
 

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/datasets/validated_datasets.py

@@ -345,7 +345,7 @@ class ForecastDataset(TimeSeriesDataset):
         """
         if self.standard_deviation_column not in self.data.columns:
             raise MissingColumnsError(missing_columns=[self.standard_deviation_column])
-        return self.data[self.standard_deviation_column]  # pyright: ignore[reportUnknownVariableType]
+        return self.data[self.standard_deviation_column]
 
     @property
     def quantiles_data(self) -> pd.DataFrame:
@@ -572,11 +572,13 @@ class EnsembleForecastDataset(TimeSeriesDataset):
         if sample_weights is not None:
             additional_columns[sample_weight_column] = sample_weights
 
-        combined_data = pd.DataFrame({
-            f"{learner}{ENSEMBLE_COLUMN_SEP}{q.format()}": ds.data[q.format()]
-            for learner, ds in datasets.items()
-            for q in ds.quantiles
-        }).assign(**additional_columns)
+        combined_data = pd.DataFrame(
+            {
+                f"{learner}{ENSEMBLE_COLUMN_SEP}{q.format()}": ds.data[q.format()]
+                for learner, ds in datasets.items()
+                for q in ds.quantiles
+            }
+        ).assign(**additional_columns)
 
         return cls(
             data=combined_data,

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/datasets/validation.py

@@ -8,8 +8,6 @@ This module provides functions to validate dataset compatibility and integrity,
 particularly for operations that combine multiple datasets.
 """
 
-import functools
-import operator
 from collections import Counter
 from collections.abc import Iterable, Sequence
 from datetime import timedelta
@@ -53,7 +51,7 @@ def validate_disjoint_columns(datasets: Iterable[TimeSeriesMixin]) -> list[str]:
     Raises:
         TimeSeriesValidationError: If any feature name appears in multiple datasets.
     """
-    all_features: list[str] = functools.reduce(operator.iadd, [d.feature_names for d in datasets], [])
+    all_features: list[str] = [feature for d in datasets for feature in d.feature_names]
     if len(all_features) != len(set(all_features)):
         duplicate_features = [item for item, count in Counter(all_features).items() if count > 1]
         raise TimeSeriesValidationError("Datasets have overlapping feature names: " + ", ".join(duplicate_features))

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/datasets/versioned_timeseries_dataset.py

@@ -182,7 +182,7 @@ class VersionedTimeSeriesDataset(TimeSeriesMixin, DatasetMixin):
         available_at_column: str = "available_at",
         horizon_column: str = "horizon",
     ) -> Self:
-        df = pd.read_parquet(path=path)  # type: ignore
+        df = pd.read_parquet(path=path)
         if "parts" in df.attrs:
             parts_metadata = json.loads(df.attrs.get("parts", "{}")).get("parts", [])
             if len(parts_metadata) == 0:
@@ -190,7 +190,7 @@ class VersionedTimeSeriesDataset(TimeSeriesMixin, DatasetMixin):
 
             parts: list[TimeSeriesDataset] = [
                 TimeSeriesDataset(
-                    data=df.loc[df.part_id == i, part_info["columns"]],
+                    data=cast("pd.DataFrame", df.loc[df.part_id == i, part_info["columns"]]),
                     sample_interval=timedelta_from_isoformat(part_info.get("sample_interval", "PT1H")),
                 )
                 for i, part_info in enumerate(parts_metadata)
@@ -251,10 +251,7 @@ class VersionedTimeSeriesDataset(TimeSeriesMixin, DatasetMixin):
             index = functools.reduce(lambda x, y: x.intersection(y), [part.index.unique() for part in data_parts])
 
         return cls(
-            data_parts=[
-                TimeSeriesDataset(data=part.data.loc[part.index.isin(index)])  # pyright: ignore[reportUnknownMemberType]
-                for part in data_parts
-            ],
+            data_parts=[TimeSeriesDataset(data=part.data.loc[part.index.isin(index)]) for part in data_parts],
             index=index,
         )
 

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/exceptions.py

@@ -12,19 +12,24 @@ from collections.abc import Sequence
 
 
 class MissingExtraError(Exception):
-    """Exception raised when an extra is missing in the extras list."""
+    """Exception raised when an optional dependency for a feature is not installed."""
 
-    def __init__(self, extra: str, package: str = "openstef-beam"):
-        """Initialize the exception with the name of the missing extra.
+    def __init__(self, extra: str, package: str = "openstef-beam", *, install_extra: str | None = None):
+        """Initialize the exception with the missing dependency and how to install it.
 
         Args:
-            extra: Name of the missing extra package.
-            package: Name of the package requiring the extra.
+            extra: Import/distribution name that failed to import (e.g. ``"onnxruntime"``).
+            package: OpenSTEF package that owns the optional feature.
+            install_extra: The extra group to install for this feature (e.g. ``"cpu"``),
+                yielding ``pip install {package}[{install_extra}]``. When ``None`` the hint
+                installs ``extra`` directly. Prefer naming the extra group: not every package
+                defines an ``[all]`` extra, and some groups are mutually exclusive.
         """
         self.extra = extra
+        target = f"{package}[{install_extra}]" if install_extra else extra
         super().__init__(
-            f"Optional package {extra} is missing. Please install it to use this module using `pip install {extra}` "
-            f"or install all optional features using `pip install {package}[all]`."
+            f"Optional dependency '{extra}' is required for this feature but is not installed. "
+            f"Install it with `pip install {target}`."
         )
 
 
@@ -100,7 +105,7 @@ class ModelUnderperformingError(Exception):
             threshold: The defined threshold for acceptable performance.
         """
         message = (
-            f"Model is underperforming: {metric_name} = {metric_value:.4f}"
+            f"Model is underperforming: {metric_name} = {metric_value:.4f} "
             f"does not meet the threshold of {threshold:.4f}."
         )
         super().__init__(message)

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/mixins/predictor.py

@@ -234,7 +234,7 @@ class HyperParams(BaseConfig):
         result: HyperParams = handler(data)
         if instance_ranges and result.__pydantic_private__ is not None:
             result._instance_ranges = instance_ranges
-        return result  # type: ignore[return-value]
+        return result  # ty: ignore[invalid-return-type]
 
     def get_search_space(self, include: set[str] | None = None) -> dict[str, TuningRange]:
         """Merge instance and class-level ranges, returning only ``tune=True`` fields.

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/mixins/stateful.py

@@ -10,7 +10,7 @@ serialization with automatic state migration.
 """
 
 import warnings
-from typing import ClassVar, TypedDict, cast
+from typing import ClassVar, TypedDict, cast, override
 
 from openstef_core.types import Any
 
@@ -41,6 +41,7 @@ class Stateful:
 
     _VERSION: ClassVar[int] = 1
 
+    @override
     def __getstate__(self) -> VersionedState:
         """Serialize object state with version metadata.
 
@@ -74,7 +75,7 @@ class Stateful:
             state: Serialized state, either VersionedState dict or legacy format.
         """
         # Handle legacy objects without versioning
-        if not isinstance(state, dict) or "__version__" not in state:  # pyright: ignore[reportUnnecessaryIsInstance]
+        if not isinstance(state, dict) or "__version__" not in state:
             warnings.warn(
                 f"Loading legacy {self.__class__.__name__} without version metadata.", UserWarning, stacklevel=2
             )
@@ -108,7 +109,7 @@ class Stateful:
         """
         # Check if any parent class has __setstate__
         if hasattr(super(), "__setstate__"):
-            super().__setstate__(state)  # type: ignore[misc]
+            super().__setstate__(state)  # ty: ignore[unresolved-attribute]
         elif state:  # Only update if state is not empty
             self.__dict__.update(state)
 

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/mixins/transform.py

@@ -130,6 +130,7 @@ class TransformPipeline[T](BaseModel, Transform[T, T]):
         description="Sequence of transforms to apply in sequence. If empty, the pipeline is a nop.",
     )
 
+    @override
     def __reduce__(self) -> tuple[Callable[[], "TransformPipeline[Any]"], tuple[()], Any]:
         """Support pickling of generic TransformPipeline instances.
 

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/testing.py

@@ -78,7 +78,7 @@ def create_timeseries_dataset(
     )
 
 
-def create_synthetic_forecasting_dataset(  # noqa: PLR0913, PLR0917 - complex function - testing utility
+def create_synthetic_forecasting_dataset(  # noqa: PLR0913 - complex function - testing utility
     start: datetime = datetime.fromisoformat("2025-01-01T00:00:00+00:00"),  # noqa: B008
     length: timedelta = timedelta(days=30 * 9),
     sample_interval: timedelta = timedelta(hours=1),
@@ -169,9 +169,6 @@ def load_liander_dataset(
     Downloads load measurements, weather forecasts, electricity prices, and standard load
     profiles from HuggingFace Hub, then combines them via left join.
 
-    Raises:
-        ImportError: When ``huggingface-hub`` is not installed.
-
     Args:
         target: Sub-path within the repo identifying the installation (e.g. ``"mv_feeder/OS Gorredijk"``).
         repo_id: HuggingFace dataset repository ID.
@@ -180,9 +177,12 @@ def load_liander_dataset(
 
     Returns:
         Combined dataset with all features aligned by timestamp.
+
+    Raises:
+        ImportError: When ``huggingface-hub`` is not installed.
     """
     try:
-        from huggingface_hub import hf_hub_download  # pyright: ignore[reportUnknownVariableType]  # noqa: PLC0415
+        from huggingface_hub import hf_hub_download  # noqa: PLC0415
         from huggingface_hub.utils import logging as hf_logging  # noqa: PLC0415
     except ImportError:
         msg = "huggingface-hub is required for benchmark datasets: pip install openstef-core[benchmark]"
@@ -199,7 +199,7 @@ def load_liander_dataset(
     # Suppress HF Hub noise (unauthenticated requests warning, progress bars)
     hf_logging.set_verbosity_error()
     for filename in files_to_download:
-        hf_hub_download(  # pyright: ignore[reportCallIssue]
+        hf_hub_download(
             repo_id=repo_id,
             filename=filename,
             repo_type="dataset",

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/types.py

@@ -18,9 +18,9 @@ from decimal import Decimal
 from enum import StrEnum
 from functools import total_ordering
 from typing import Any, Literal, Self, override
+from zoneinfo import ZoneInfo
 
 import pandas as pd
-import pytz
 from pydantic import GetCoreSchemaHandler, TypeAdapter, ValidationInfo
 from pydantic_core import CoreSchema, core_schema
 
@@ -55,6 +55,7 @@ class LeadTime(PydanticStringPrimitive):
         """
         self.value = value
 
+    @override
     def __str__(self) -> str:
         """Converts to ISO 8601 duration string.
 
@@ -63,6 +64,7 @@ class LeadTime(PydanticStringPrimitive):
         """
         return TypeAdapter(timedelta).dump_python(self.value, mode="json")
 
+    @override
     def __repr__(self) -> str:
         """Returns a detailed string representation for debugging.
 
@@ -72,6 +74,7 @@ class LeadTime(PydanticStringPrimitive):
         return f"LeadTime('{self}')"
 
     @classmethod
+    @override
     def from_string(cls, s: str) -> Self:
         """Creates an instance from an ISO 8601 duration string.
 
@@ -131,10 +134,10 @@ class AvailableAt(PydanticStringPrimitive):
     - *HHMM* is the time of day
 
     An optional timezone suffix ``[Region/City]`` (RFC 9557 bracket
-    notation) makes the availability time timezone-aware.  Both pytz
+    notation) makes the availability time timezone-aware.  ``zoneinfo``
     and stdlib ``datetime.timezone`` objects are accepted; they
     round-trip through the IANA name via ``str(tz)`` /
-    ``pytz.timezone(name)``.
+    ``zoneinfo.ZoneInfo(name)``.
 
     For example, ``D-1T0600[Europe/Amsterdam]`` means "6:00
     Europe/Amsterdam on the previous day".
@@ -143,8 +146,8 @@ class AvailableAt(PydanticStringPrimitive):
 
     Example:
         >>> from datetime import time
-        >>> import pytz
-        >>> tz_at = AvailableAt(day_offset=-1, time_of_day=time(6, 0), tzinfo=pytz.timezone('Europe/Amsterdam'))
+        >>> from zoneinfo import ZoneInfo
+        >>> tz_at = AvailableAt(day_offset=-1, time_of_day=time(6, 0), tzinfo=ZoneInfo('Europe/Amsterdam'))
         >>> str(tz_at)
         'D-1T0600[Europe/Amsterdam]'
         >>> at = AvailableAt.from_string("D-1T0600")
@@ -152,7 +155,7 @@ class AvailableAt(PydanticStringPrimitive):
         (-1, datetime.time(6, 0))
     """
 
-    def __init__(self, day_offset: int, time_of_day: time, *, tzinfo: pytz.BaseTzInfo | dt_timezone | None = None):
+    def __init__(self, day_offset: int, time_of_day: time, *, tzinfo: ZoneInfo | dt_timezone | None = None):
         """Initialise with a day offset, time of day, and optional timezone.
 
         Args:
@@ -160,7 +163,7 @@ class AvailableAt(PydanticStringPrimitive):
                 ``-1`` means "the previous day", ``0`` means "the same day".
             time_of_day: Clock time when data becomes available.
             tzinfo: Optional timezone for the availability time
-                (e.g. ``pytz.timezone("Europe/Amsterdam")``, ``pytz.UTC``,
+                (e.g. ``zoneinfo.ZoneInfo("Europe/Amsterdam")``, ``zoneinfo.ZoneInfo("UTC")``,
                 or ``datetime.timezone.utc``).
 
         Raises:
@@ -173,6 +176,7 @@ class AvailableAt(PydanticStringPrimitive):
         self.time_of_day = time_of_day
         self.tzinfo = tzinfo
 
+    @override
     def __str__(self) -> str:
         """Converts to string in ``DnTHHMM`` or ``DnTHHMM[tz]`` format.
 
@@ -185,6 +189,7 @@ class AvailableAt(PydanticStringPrimitive):
         return base
 
     @classmethod
+    @override
     def from_string(cls, s: str) -> Self:
         """Creates an instance from a string in ``DnTHHMM[tz]`` format.
 
@@ -212,9 +217,9 @@ class AvailableAt(PydanticStringPrimitive):
             raise ValueError(msg)
 
         if z_part:
-            resolved_tz = pytz.UTC
+            resolved_tz = ZoneInfo("UTC")
         elif tz_part:
-            resolved_tz = pytz.timezone(tz_part)
+            resolved_tz = ZoneInfo(tz_part)
         else:
             resolved_tz = None
 
@@ -256,10 +261,7 @@ class AvailableAt(PydanticStringPrimitive):
         if source_tz is None:
             return naive_result
 
-        if isinstance(source_tz, pytz.BaseTzInfo):
-            aware = source_tz.localize(naive_result)
-        else:
-            aware = naive_result.replace(tzinfo=source_tz)
+        aware = naive_result.replace(tzinfo=source_tz)
 
         if date.tzinfo is not None:
             return aware.astimezone(date.tzinfo)

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/utils/__init__.py

@@ -19,6 +19,10 @@ from openstef_core.utils.invariants import (
 from openstef_core.utils.multiprocessing import (
     run_parallel,
 )
+from openstef_core.utils.numpy import (
+    interpolate_quantiles,
+    zero_fill_with_mask,
+)
 from openstef_core.utils.pydantic import (
     timedelta_from_isoformat,
     timedelta_to_isoformat,
@@ -27,8 +31,10 @@ from openstef_core.utils.pydantic import (
 __all__ = [
     "align_datetime",
     "align_datetime_to_time",
+    "interpolate_quantiles",
     "not_none",
     "run_parallel",
     "timedelta_from_isoformat",
     "timedelta_to_isoformat",
+    "zero_fill_with_mask",
 ]

{openstef_core-4.0.1 → openstef_core-4.1.1.dev0}/src/openstef_core/utils/multiprocessing.py

@@ -63,12 +63,10 @@ def run_parallel[T, R](
         return [process_fn(item) for item in items]
 
     if mode == "loky":
-        from joblib import Parallel, delayed  # pyright: ignore[reportUnknownVariableType] # noqa: PLC0415
+        from joblib import Parallel, delayed  # noqa: PLC0415
 
         # Use joblib with loky backend for robust process management
-        return Parallel(n_jobs=n_processes, backend="loky")(  # pyright: ignore[reportUnknownVariableType]
-            delayed(process_fn)(item) for item in items
-        )  # type: ignore
+        return Parallel(n_jobs=n_processes, backend="loky")(delayed(process_fn)(item) for item in items)
 
     # Auto-configure for macOS
     context = multiprocessing.get_context(method=mode)

openstef_core-4.1.1.dev0/src/openstef_core/utils/numpy.py

@@ -0,0 +1,105 @@
+# SPDX-FileCopyrightText: 2025 Contributors to the OpenSTEF project <openstef@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Pure NumPy helpers for probabilistic forecasting."""
+
+import logging
+from collections.abc import Sequence
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def zero_fill_with_mask(values: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Split an array into a zero-filled copy and a finiteness mask.
+
+    Non-finite entries (``NaN`` or infinities) are replaced with ``0.0`` in the
+    returned values; the mask is ``1.0`` exactly where the original entry was
+    finite. This is the common "feed raw values, tell the model which are real"
+    step for masked model inputs.
+
+    Args:
+        values: Array of any shape.
+
+    Returns:
+        Tuple ``(filled, mask)``, both ``float32`` and the same shape as
+        *values*. ``filled`` has non-finite entries zeroed; ``mask`` is ``1.0``
+        where *values* was finite, ``0.0`` otherwise.
+    """
+    finite = np.isfinite(values)
+    filled = np.where(finite, values, np.float32(0.0)).astype(np.float32)
+    return filled, finite.astype(np.float32)
+
+
+def interpolate_quantiles(
+    predictions: np.ndarray,
+    source_quantiles: Sequence[float],
+    target_quantiles: Sequence[float],
+) -> np.ndarray:
+    """Resample quantile predictions onto a new quantile grid.
+
+    Performs piecewise-linear interpolation across the quantile dimension (the
+    last axis of *predictions*). Target levels outside the source range are
+    clamped to the nearest source prediction (constant extrapolation), which
+    keeps the resampled values within the predicted envelope. Because the model
+    cannot say anything beyond its most extreme level, a request for, say, q0.999
+    against a model whose highest level is q0.99 returns the q0.99 prediction; a
+    warning is logged whenever this clamping happens.
+
+    Args:
+        predictions: Array of shape ``(..., n_source)`` whose last axis holds
+            predictions for each level in *source_quantiles*, in the same order.
+        source_quantiles: Strictly ascending quantile levels the model emits.
+        target_quantiles: Quantile levels to resample onto. Any order.
+
+    Returns:
+        Array of shape ``(..., n_target)`` with predictions for each level in
+        *target_quantiles*, in the same order.
+
+    Raises:
+        ValueError: If *source_quantiles* is not strictly ascending, or its
+            length does not match the last axis of *predictions*.
+    """
+    src = np.asarray(source_quantiles, dtype=np.float64)
+    tgt = np.asarray(target_quantiles, dtype=np.float64)
+
+    min_levels = 2  # need at least two source levels to interpolate between
+    if src.ndim != 1 or src.shape[0] < min_levels:
+        msg = "source_quantiles must be a 1-D sequence with at least two levels."
+        raise ValueError(msg)
+    if predictions.shape[-1] != src.shape[0]:
+        msg = (
+            f"predictions last axis ({predictions.shape[-1]}) must match the number "
+            f"of source quantiles ({src.shape[0]})."
+        )
+        raise ValueError(msg)
+    if np.any(np.diff(src) <= 0):
+        msg = "source_quantiles must be strictly ascending."
+        raise ValueError(msg)
+
+    out_of_range = tgt[(tgt < src[0]) | (tgt > src[-1])]
+    if out_of_range.size:
+        logger.warning(
+            "Target quantile level(s) %s lie outside the source range [%s, %s]; "
+            "clamping to the nearest source quantile (constant extrapolation).",
+            np.unique(out_of_range).tolist(),
+            src[0],
+            src[-1],
+        )
+
+    # Bracket each target level by the adjacent source levels, clamping the
+    # endpoints so out-of-range targets extrapolate as constants.
+    upper = np.clip(np.searchsorted(src, tgt, side="left"), 1, src.shape[0] - 1)
+    lower = upper - 1
+
+    weight = (tgt - src[lower]) / (src[upper] - src[lower])
+    weight = np.clip(weight, 0.0, 1.0)
+
+    low_values = predictions[..., lower]
+    high_values = predictions[..., upper]
+    return low_values * (1.0 - weight) + high_values * weight
+
+
+__all__ = ["interpolate_quantiles", "zero_fill_with_mask"]