QuantileProbabilityPlotter#

class openstef_beam.analysis.plots.quantile_probability_plotter.QuantileProbabilityPlotter[source]

Bases: object

Creates calibration plots comparing forecasted vs observed probabilities.

This plotter validates probabilistic forecasts by examining whether predicted uncertainty levels match actual outcomes. The resulting plots help answer:

  • Are 90% confidence intervals correct 90% of the time?

  • Do models over-estimate or under-estimate forecast uncertainty?

  • Which model provides the most reliable uncertainty quantification?

  • How well-calibrated are different quantile predictions?

The plots show:

  • Scatter plots of forecasted vs observed probabilities

  • Perfect calibration diagonal line for reference

  • Model-specific calibration curves

  • Visual indicators of over/under-confidence

Well-calibrated models will have points close to the diagonal line, while systematic deviations indicate bias in uncertainty estimation.

Example

Validating forecast calibration

>>> from openstef_core.types import Quantile
>>> plotter = QuantileProbabilityPlotter()
>>>
>>> # Add model calibration data
>>> forecasted = [Quantile(0.1), Quantile(0.3), Quantile(0.5), Quantile(0.9)]
>>> observed = [Quantile(0.12), Quantile(0.28), Quantile(0.52), Quantile(0.88)]
>>> _ = plotter.add_model("XGBoost", forecasted, observed)
>>> # Generate calibration plot
>>> fig = plotter.plot(title="Forecast Calibration Analysis")
>>> type(fig).__name__
'Figure'
__init__()[source]

Initialize the plotter with empty model data storage.

add_model(model_name: str, forecasted_probs: list[Quantile], observed_probs: list[Quantile]) → QuantileProbabilityPlotter[source]

Add a model’s forecasted and observed probabilities to the plot.

Parameters:

  • model_name (str) – The name of the model.

  • forecasted_probs (list[Quantile]) – List of forecasted probabilities.

  • observed_probs (list[Quantile]) – List of observed probabilities.

  • model_name

  • forecasted_probs

  • observed_probs

Returns:

The current instance for method chaining.

Return type:

QuantileProbabilityPlotter

Raises:

ValueError – If forecasted and observed probability lists have different lengths.

Return type:

QuantileProbabilityPlotter

plot(title: str = 'Quantile probability plot') → Figure[source]

Create and return a quantile probability plot for all added models.

Parameters:

  • title (str) – Title of the plot.

  • title

Returns:

The resulting plot.

Return type:

plotly.graph_objects.Figure

Raises:

ValueError – If no model data has been added.

Return type:

Figure