fusionlab.plot.evaluation.plot_prediction_stability¶

fusionlab.plot.evaluation.plot_prediction_stability(y_pred, pss_values=None, metric_kws=None, kind='summary_bar', output_idx=None, hist_bins='auto', hist_color='teal', hist_edgecolor='black', figsize=(10, 6), title='Prediction Stability Score (PSS)', xlabel=None, ylabel=None, bar_color='teal', bar_width=0.8, score_annotation_format='{:.4f}', show_score=True, show_grid=True, grid_props=None, ax=None, verbose=0, **kwargs)[source]¶

Visualise the Prediction Stability Score (PSS) — the average absolute change between successive time steps in a forecast trajectory. Lower PSS ⇒ smoother (more stable) predictions.

Two complementary views are provided:

‘scores_histogram’ – distribution of per‑trajectory PSS values for a chosen output.
‘summary_bar’ – bar chart of the mean PSS (overall or one bar per output).

Parameters:

y_pred (ndarray) – Model predictions. Accepts * 1‑D (T,) – single trajectory, one output; * 2‑D (N, T) – N trajectories, one output; * 3‑D (N, O, T) – N trajectories, O outputs. The final dimension is the temporal axis (T ≥ 2 for PSS).
pss_values (float or ndarray, optional) – Pre‑computed PSS value(s). If supplied the helper skips internal calls to fusionlab.metrics.prediction_stability_score().
metric_kws (dict, optional) – Extra keyword arguments forwarded to the metric function.
kind ({'scores_histogram', 'summary_bar'},) – default 'summary_bar' Select the visualisation style.
output_idx (int, optional) – Output dimension to plot when kind='scores_histogram' on multi‑output data.
hist_bins (int | sequence | str, default :class:``’auto’:class:``)
hist_color (str, default :class:``’teal’:class:``)
hist_edgecolor (str, default :class:``’black’:class:``) – Styling options for the histogram.
figsize (tuple of float, optional) – Size of the figure in inches (width, height). If omitted the
title (str, optional) – Main title for the figure. If None, a context‑aware default
xlabel (str, optional) – Label for the x‑axis. If None, a function‑specific default is
ylabel (str, optional) – Label for the y‑axis. If None, a context‑sensitive default is
bar_color (str or list of str, optional) – Bar face‑colour(s). Accepts any Matplotlib‑recognised colour
bar_width (float, default 0.8)
score_annotation_format (str, default '{:.4f}') – Python format string used for numeric annotations. Examples:
show_score (bool, default True) – Display the mean PSS on the histogram title.
show_grid (bool, default True)
grid_props (dict, optional) – Keyword arguments forwarded to Axes.grid for fine‑grained
ax (matplotlib.axes.Axes, optional) – Existing Matplotlib axes to draw on. If None, a new figure
verbose (int, default 0) – Verbosity level. 0 ⇒ silent, 1 ⇒ basic info, 2+ ⇒ debug
**kwargs – Additional keyword arguments passed directly to the underlying Matplotlib primitives (plot, scatter, bar,

Returns:

Axes containing the stability visualisation.

Return type:

matplotlib.axes.Axes

Notes

For one trajectory \((\hat y_{1},\dots,\hat y_{T})\) the stability score is

\[\operatorname{PSS} \;=\; \frac{1}{T-1}\sum_{t=2}^{T} \bigl|\hat y_{t} - \hat y_{t-1}\bigr|.\]

The helper first reshapes y_pred to (N, O, T), computes the per‑trajectory scores, and then aggregates or plots them according to kind.

Examples

>>> import numpy as np, matplotlib.pyplot as plt
>>> from fusionlab.plot.evaluation import plot_prediction_stability
>>> rng = np.random.default_rng(0)
>>> preds = rng.normal(size=(200, 30))      # 200 series, 30 time steps
>>> plot_prediction_stability(
...     preds, kind='scores_histogram', figsize=(8, 4))
>>> plt.show()