fusionlab.plot.evaluation.plot_weighted_interval_score¶

fusionlab.plot.evaluation.plot_weighted_interval_score(y_true, y_median, y_lower, y_upper, alphas, metric_values=None, metric_kws=None, kind='summary_bar', output_idx=None, hist_bins='auto', hist_color='mediumseagreen', hist_edgecolor='black', figsize=(10, 6), title='Weighted Interval Score (WIS)', xlabel=None, ylabel=None, bar_color='mediumseagreen', bar_width=0.8, score_annotation_format='{:.4f}', show_score_on_title=True, show_grid=True, grid_props=None, ax=None, verbose=0, **kwargs)[source]¶

Visualise Weighted Interval Score (WIS).

WIS aggregates interval widths and coverage penalties across a set of central prediction intervals, producing a proper scoring rule that simultaneously rewards sharpness and calibration of probabilistic forecasts [1].

The helper provides two complementary views:

‘summary_bar’ – one bar per output (or a single bar for the uniform average).
‘scores_histogram’ – the distribution of per‑sample WIS values for a selected output.

Parameters:

y_true (ndarray of shape (n_samples, …)) – Ground‑truth target values. Depending on the metric a 1‑D array (global aggregation), a 2‑D array (n_samples, n_outputs), or a 3‑D array (n_samples, n_horizons, n_outputs) may be
y_median (ndarray) – Median (50 % quantile) forecast, shape compatible with y_true.
y_lower (ndarray) – Lower‑bound quantile (e.g. 0.05 or 0.10) for an uncertainty interval. Shape must mirror y_true. Required by coverage,
y_upper (ndarray) – Upper‑bound quantile (e.g. 0.95 or 0.90) paired with y_lower.
alphas (ndarray of shape (K,)) – Alpha levels that define the nominal coverage of each prediction interval: \(\alpha_k = 1 - (q_{k+1} - q_k)\). Must satisfy 0 < α < 1 and be strictly increasing.
metric_values (float or ndarray, optional) – Pre‑computed WIS value(s). When supplied, plotting is performed without recalculating the metric.
metric_kws (dict, optional) – Extra keyword arguments forwarded to fusionlab.metrics.weighted_interval_score() (e.g. multioutput='raw_values').
kind ({'summary_bar', 'scores_histogram'}, default :class:``’summary_bar’:class:``) – Style of visualisation.
output_idx (int, optional) – Index of the target variable to visualise when kind='scores_histogram' on multi‑output data.
hist_bins (int | sequence | str, default :class:``’auto’:class:``) – Binning strategy for the histogram (passed to matplotlib.pyplot.hist()).
hist_color (str, default :class:``’mediumseagreen’:class:``)
hist_edgecolor (str, default :class:``’black’:class:``) – Bar‑face and edge colours for the histogram.
figsize (tuple of float, optional) – Size of the figure in inches (width, height). If omitted the
title (str, optional) – Custom figure title. If None, a context‑aware title is generated.
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_on_title (bool, default True) – Append the mean WIS to the title when kind='scores_histogram'.
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:

The axes object containing the plot.

Return type:

matplotlib.axes.Axes

Notes

The weighted interval score for a single observation and \(K\) central prediction intervals is

\[\mathrm{WIS} \;=\; \frac{1}{K + 0.5}\;\Bigl[ \lvert y - \hat{y}_{0.5}\rvert\;+\; \sum_{k=1}^{K} \alpha_k \bigl\{\, (y < l_k)\,(l_k - y) + (y > u_k)\,(y - u_k) + (u_k - l_k) \bigr\} \Bigr],\]

where \([l_k, u_k]\) is the \((1-\alpha_k)\) central interval. Lower WIS indicates a sharper, better‑calibrated forecast.

Examples

>>> import numpy as np, matplotlib.pyplot as plt
>>> from fusionlab.plot.evaluation import plot_weighted_interval_score
>>> rng = np.random.default_rng(0)
>>> y_true   = rng.normal(size=100)
>>> y_med    = y_true + rng.normal(scale=.1, size=100)
>>> y_lower  = y_med - 1.0
>>> y_upper  = y_med + 1.0
>>> alphas   = np.array([0.2])
>>> plot_weighted_interval_score(y_true, y_med,
...                              y_lower, y_upper, alphas,
...                              kind='summary_bar',
...                              bar_color='slateblue')
>>> plt.show()