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()