fusionlab.plot.evaluation.plot_forecast_comparison¶

fusionlab.plot.evaluation.plot_forecast_comparison(forecast_df, target_name='target', quantiles=None, output_dim=1, kind='temporal', actual_data=None, dt_col=None, actual_target_name=None, sample_ids='first_n', num_samples=3, horizon_steps=1, spatial_cols=None, max_cols=2, figsize_per_subplot=(7, 4), scaler=None, scaler_feature_names=None, target_idx_in_scaler=None, titles=None, verbose=0, **plot_kwargs)[source]¶

Compare forecasts to ground‑truth on a temporal or spatial canvas.

The helper draws either

temporal lines/bands – one subplot per (sample × output‑dim) pair – or
spatial scatter maps keyed by longitude/latitude columns,

depending on kind. Point‑ and quantile‑forecasts exported by fusionlab.nn.utils.format_predictions_to_dataframe() are supported out‑of‑the‑box.

Parameters:

forecast_df (pandas.DataFrame) – Long‑format table of predictions. Must contain 'sample_idx' and 'forecast_step' plus the prediction, {segment_col}, and actual columns (for instance
target_name (str, default :class:``”target”:class:``)
quantiles (list[float], optional) – Quantiles included in forecast_df (e.g. [0.1, 0.5, 0.9]). If present and a generic metric is chosen the median (0.5 or nearest) prediction is employed as y_pred.
output_dim (int, default 1) – Number of target dimensions. A separate radar is generated
kind ({'temporal', 'spatial'}, default :class:``’temporal’:class:``) – Temporal plots show each horizon step on the x‑axis; spatial plots colour‑code predictions on a map using spatial_cols.
actual_data (pd.DataFrame, optional) – External frame providing the true series (useful when the forecast_df only contains predictions).
dt_col (str, optional) – Name of a datetime column to place on the x‑axis instead of 'forecast_step'.
actual_target_name (str, optional) – Base name of the true values when it differs from target_name.
sample_ids (int | list[int] | str, default :class:``’first_n’:class:``) –
Which sample_idx to visualise:
- int – by position,
- list – explicit indices,
- 'first_n'/'all'.
num_samples (int, default 3) – How many samples to draw when sample_ids=’first_n’.
horizon_steps (int | list[int] | str, default 1) – For kind=’spatial’ choose which forecast steps to map (may be 'all').
spatial_cols (list[str], optional) – [x_col, y_col] (e.g. longitude, latitude) required for spatial plots.
max_cols (int, default 2) – Maximum subplot columns in the facet grid.
figsize_per_subplot (tuple, default :class:`(7`:class:`, `:class:`4)`) – Width × height of each panel in inches.
scaler (Any, optional) – Fitted scikit‑learn‑style transformer used to inverse‑scale data
scaler_feature_names (list[str], optional) – Full feature order that scaler was trained on.
target_idx_in_scaler (int, optional) – Position of target_name inside scaler_feature_names.
titles (list[str], optional) – Per‑subplot custom titles (overrides defaults).
verbose (int, default 0)
**plot_kwargs (Any) – Extra arguments forwarded to the underlying Matplotlib ax.plot / ax.fill calls (e.g. color, linewidth,

Returns:

The function shows Matplotlib figures and exits.

Return type:

None

Raises:

ValueError – If essential columns are missing or arguments conflict.
TypeError – For invalid forecast_df or parameter types.

Notes

Temporal plots draw the median and an optional prediction band (using the outermost quantiles). When quantiles is None a single point‑forecast series is shown.

Examples

>>> from fusionlab.nn.utils import format_predictions_to_dataframe
>>> from fusionlab.plot.evaluation import plot_forecast_comparison
>>> import numpy as np
>>> B, H, O = 4, 6, 1
>>> preds = np.random.randn(B, H, O)
>>> y     = preds + np.random.randn(B, H, O)*.2
>>> df    = format_predictions_to_dataframe(preds, y,
...         target_name="load", forecast_horizon=H)
>>> plot_forecast_comparison(df, target_name="load",
...                          kind="temporal", num_samples=2)