ForecastTimeSeriesPlotter#

class openstef_beam.analysis.plots.ForecastTimeSeriesPlotter(**data: Any) → None[source]

Bases: BaseConfig

Creates interactive time series charts comparing forecasts, measurements, and uncertainty bands.

This plotter visualizes forecast performance over time by overlaying multiple models’ predictions, actual measurements, and uncertainty quantiles on a single chart. The resulting interactive plots help answer questions like:

  • How do different models’ forecasts compare to actual values over time?

  • Which model provides the most accurate short-term vs long-term predictions?

  • How well do uncertainty bands capture actual forecast errors?

  • Are there seasonal or temporal patterns in model performance?

The plots include:

  • Line charts for measurements (actual values) and model forecasts

  • Shaded confidence bands showing forecast uncertainty (quantiles)

  • Color-coded models for easy visual comparison

  • Interactive hover information and zooming capabilities

Example

Basic usage comparing forecast to measurements

>>> from openstef_core.datasets import TimeSeriesDataset
>>> import pandas as pd
>>> from datetime import timedelta
>>> # Create sample data
>>> dates = pd.date_range('2024-01-01', periods=10, freq='h')
>>> measurements = pd.Series(data=range(10), index=dates, name="measurements")
>>> forecast = pd.Series(data=[x + 1 for x in range(10)], index=dates, name="forecast")
>>>
>>> # Create and configure plotter
>>> plotter = ForecastTimeSeriesPlotter()
>>> _ = plotter.add_measurements(measurements)
>>> _ = plotter.add_model("XGBoost", forecast=forecast)
>>> fig = plotter.plot(title="Energy Forecast Comparison")
>>> type(fig).__name__
'Figure'
Parameters:

data (Any)

MEDIAN_QUANTILE: ClassVar[float] = 50.0
COLOR_SCHEME: ClassVar[dict[str, str]] = {'blue': 'Blues', 'green': 'Greens', 'grey': 'Greys', 'magenta': 'Magenta', 'orange': 'Oranges', 'purple': 'Purples'}
colors: ClassVar[list[str]] = ['blue', 'green', 'purple', 'orange', 'magenta', 'grey']
colormaps: ClassVar[list[str]] = ['Blues', 'Greens', 'Purples', 'Oranges', 'Magenta', 'Greys']
colormap_range: tuple[float, float]
fill_opacity: float
stroke_opacity: float
stroke_width: float
sample_interval: timedelta
connect_gaps: bool
add_measurements(measurements: Series) → Self[source]

Add measurements (realized values) to the plot.

Parameters:

  • measurements (Series) – A Pandas Series containing the realized values.

  • measurements

Returns:

The current instance for method chaining.

Return type:

ForecastTimeSeriesPlotter

Return type:

Self

add_model(model_name: str, forecast: Series | None = None, quantiles: DataFrame | None = None) → ForecastTimeSeriesPlotter[source]

Add a model’s forecast and/or quantile data to the plot.

Parameters:

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

  • forecast (Series | None) – A pd.Series containing the forecasted values.

  • quantiles (DataFrame | None) – A pd.DataFrame containing quantile data. Column names should follow the format ‘quantile_P{percentile:02d}’, e.g., ‘quantile_P10’, ‘quantile_P90’.

  • model_name

  • forecast

  • quantiles

Returns:

The current instance for method chaining.

Return type:

ForecastTimeSeriesPlotter

Raises:

ValueError – If neither forecast nor quantiles are provided, or if quantile column names don’t follow the expected format.

Return type:

ForecastTimeSeriesPlotter

add_limit(value: float, name: str | None = None) → ForecastTimeSeriesPlotter[source]

Add a horizontal limit line to the plot.

Parameters:

  • value (float) – The y-value where the limit line should be drawn.

  • name (str | None) – The name of the limit to be displayed in the legend. If not provided, will be named “Limit N” where N is the index.

  • value

  • name

Returns:

The current instance for method chaining.

Return type:

ForecastTimeSeriesPlotter

Return type:

ForecastTimeSeriesPlotter

plot(title: str = 'Time Series Plots') → Figure[source]

Plot the time series data with measurements, forecasts, and quantiles.

Parameters:

  • title (str) – Title of the plot.

  • title

Returns:

The time series plot.

Return type:

plotly.graph_objects.Figure

Raises:

ValueError – If no data has been added to the plotter.

Return type:

Figure

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'protected_namespaces': ()}

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

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

  • self (BaseModel) – The BaseModel instance.

  • context (Any) – The context.

  • self

  • context

Return type:

None