fusionlab.plot.evaluation.plot_coverage

fusionlab.plot.evaluation.plot_coverage(y_true, y_lower, y_upper, coverage_values=None, metric_kws=None, sample_indices=None, output_index=None, kind='intervals', figsize=(12, 6), title='Prediction Interval Coverage', xlabel='Sample Index', ylabel='Value', covered_color='mediumseagreen', uncovered_color='salmon', line_color='dimgray', line_style='--', line_width=0.8, marker='o', marker_size=30, interval_color='skyblue', interval_alpha=0.5, legend=True, show_score=True, bar_color='cornflowerblue', bar_width=0.8, score_annotation_format='{:.2%}', show_grid=True, grid_props=None, ax=None, verbose=0, **kwargs)[source]

Visualise prediction‑interval coverage in two ways:

  • ‘intervals’ – true values overlaid on their prediction intervals, coloured by whether each point is covered.

  • ‘summary_bar’ – bar chart of the empirical coverage rate (overall or per 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_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.

  • coverage_values (float or ndarray, optional) – Pre‑computed coverage score(s). If supplied, the helper skips the internal call to fusionlab.metrics.coverage_score().

  • metric_kws (dict, optional) – Extra keyword arguments forwarded to fusionlab.metrics.coverage_score() when coverage_values is None.

  • sample_indices (ndarray, optional) – Custom x‑axis locations for the ‘intervals’ plot. Must match the first dimension of y_true.

  • output_index (int, optional) – Output dimension to visualise when the data contain multiple outputs and kind='intervals'.

  • kind ({'intervals', 'summary_bar'}, default :class:``’intervals’:class:``) – Select the visualisation style.

  • figsize (tuple of float, optional) – Size of the figure in inches (width, height). If omitted the

  • title (str, optional) – Figure title. If None, a context‑aware default is generated.

  • xlabel (str, default :class:``’Sample Index’:class:``)

  • ylabel (str, default :class:``’Value’:class:``)

  • styling (Summary‑bar)

  • ^^^^^^^^^^^^^^^^^^^^^

  • covered_color (str, default :class:``’mediumseagreen’:class:``)

  • uncovered_color (str, default :class:``’salmon’:class:``)

  • line_color (str or None, default :class:``’dimgray’:class:``)

  • line_style (str, default :class:``’–’:class:``)

  • line_width (float, default 0.8)

  • marker (str, default :class:``’o’:class:``)

  • marker_size (int, default 30)

  • interval_color (str, default :class:``’skyblue’:class:``)

  • interval_alpha (float, default 0.5)

  • legend (bool, default True)

  • show_score (bool, default True) – Append the empirical coverage (as a percentage) to the title of the intervals plot.

  • styling

  • ^^^^^^^^^^^^^^^^^^^

  • 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_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 coverage visualisation.

Return type:

matplotlib.axes.Axes

Notes

The empirical coverage for one output is

\[\widehat C \;=\; \frac{1}{N} \sum_{i=1}^{N} \mathbb{1}\{\,y_i \in [\ell_i, u_i]\,\},\]

where \([\ell_i, u_i]\) is the prediction interval for sample i. The helper colours covered points with covered_color and uncovered points with uncovered_color.

Examples

>>> import numpy as np, matplotlib.pyplot as plt
>>> from fusionlab.plot.evaluation import plot_coverage
>>> rng = np.random.default_rng(1)
>>> y_true  = rng.normal(size=50)
>>> y_lower = y_true - 1.0
>>> y_upper = y_true + 1.0
>>> plot_coverage(y_true, y_lower, y_upper, kind='intervals',
...               figsize=(8, 4))
>>> plt.show()

See also

fusionlab.metrics.coverage_score

Numerical implementation of empirical coverage.

fusionlab.plot.evaluation.plot_weighted_interval_score

Visualises interval sharpness and calibration jointly.

fusionlab.plot.evaluation.plot_quantile_calibration

Reliability diagrams for quantile forecasts.

References