ConfidenceIntervalApplicator#

class openstef_models.transforms.postprocessing.confidence_interval_applicator.ConfidenceIntervalApplicator(**data: Any) → None[source]

Bases: BaseModel, Transform[ForecastDataset, ForecastDataset]

Add quantile predictions to forecasts based on learned uncertainty patterns.

This transform learns hour-specific uncertainty from fit errors and applies it to new predictions to generate probabilistic forecasts.

How it works:

  1. Learning phase (fit()):

    • Computes fit errors for each hour of day (0-23)

    • Uses pooled error variability when an hour has too few samples

    • For multi-horizon data, stores separate std for each horizon

  2. Prediction phase (transform()):

    • Looks up appropriate std based on prediction hour

    • For multi-horizon: interpolates std using exponential decay

    • Converts std to quantiles assuming a normal distribution (e.g., P10 = median - 1.28*std, P90 = median + 1.28*std)

The exponential decay interpolation (for multi-horizon) uses sigma(t) = a * (1 - exp(-t/tau)) + b, where t is hours ahead and tau = far_horizon / 4. This reflects the pattern of uncertainty growing quickly at first then leveling off.

Parameters:

quantiles (list[Quantile] | None) – Quantiles to generate (e.g., [0.1, 0.5, 0.9]). If None, returns predictions unchanged.

Invariants

  • Validation data must span multiple days for reliable hourly statistics

  • Generated quantiles satisfy ordering: P10 <= P50 <= P90 (for typical quantiles)

Example

>>> from openstef_core.types import LeadTime, Quantile
>>> from datetime import timedelta
>>> applicator = ConfidenceIntervalApplicator(
...     quantiles=[Quantile(0.1), Quantile(0.5), Quantile(0.9)]
... )
>>> applicator.fit((validation_data, validation_predictions))
>>> result = applicator.transform((new_input_data, new_predictions))
>>> list(result.data.columns)
['quantile_P10', 'quantile_P50', 'quantile_P90']

Note

Assumes forecast errors follow a normal distribution. This works well for energy forecasting but may not suit all domains.

Parameters:

data (Any)

quantiles: list[Quantile] | None
add_quantiles_from_std: bool
model_post_init(_context: object, /) → None[source]

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:

_context (object)

Return type:

None

property standard_deviation: DataFrame

Hour-specific standard deviations learned during fit.

Raises:

NotFittedError – If fit() has not been called.

property is_fitted: bool

Check if the transform has been fitted.

fit(data: ForecastDataset) → None[source]

Fit the transform to the input data.

This method should be called before applying the transform to the data. It allows the transform to learn any necessary parameters from the data.

Parameters:
Return type:

None

transform(data: ForecastDataset) → ForecastDataset[source]

Transform the input data.

This method should apply a transformation to the input data and return a new instance.

Parameters:
Returns:

A new instance of the transformed data.

Raises:

NotFittedError – If the transform has not been fitted yet.

Return type:

ForecastDataset

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].