fusionlab.plot.evaluation.plot_quantile_calibration¶

fusionlab.plot.evaluation.plot_quantile_calibration(y_true, y_pred_quantiles, quantiles, qce_values=None, metric_kws=None, kind='reliability_diagram', output_idx=None, perfect_calib_color='red', observed_prop_color='blue', observed_prop_marker='o', figsize=(8, 8), title='Quantile Calibration Error (QCE)', xlabel=None, ylabel=None, bar_color='darkcyan', bar_width=0.8, score_annotation_format='{:.4f}', show_score=True, show_grid=True, grid_props=None, ax=None, verbose=0, **kwargs)[source]¶

Visualise Quantile Calibration Error (QCE).

Two complementary views are supported:

‘reliability_diagram’ – plots the observed proportion \(\Pr(y \le \hat q)\) against the nominal quantile level q. Perfect calibration lies on the diagonal.
‘summary_bar’ – one bar per output (or an overall bar) showing the time‑weighted QCE score.

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_pred_quantiles (ndarray) – Stack of predictive quantiles. Typical shape is (n_samples, n_horizons, n_quantiles) or
quantiles (1‑D ndarray) – Numeric array of the quantile levels represented in y_pred_quantiles, sorted in ascending order
qce_values (float or ndarray, optional) – Pre‑computed QCE value(s). If supplied, the helper skips internal metric evaluation.
metric_kws (dict, optional) – Extra keyword arguments passed to fusionlab.metrics.quantile_calibration_error().
kind ({'reliability_diagram', 'summary_bar'},) – default 'reliability_diagram' Choose the visualisation style.
output_idx (int, optional) – Output dimension to plot when the data contain multiple outputs and kind='reliability_diagram'.
perfect_calib_color (str, default :class:``’red’:class:``) – Line colour for the 45‑degree “perfect calibration’’ reference.
observed_prop_color (str, default :class:``’blue’:class:``)
observed_prop_marker (str, default :class:``’o’:class:``) – Style for the observed‑proportion curve.
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 average QCE on the plot or 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 calibration plot.

Return type:

matplotlib.axes.Axes

Notes

The quantile calibration error for one output is

\[\mathrm{QCE} \;=\; \frac{1}{Q}\sum_{k=1}^{Q} \bigl|\, \hat F_y(q_k) \;-\; q_k \bigr|,\]

where \(\hat F_y(q_k)\) is the empirical cdf evaluated at the predicted quantile \(\hat q_k\).

Examples

>>> import numpy as np, matplotlib.pyplot as plt
>>> from fusionlab.plot.evaluation import plot_quantile_calibration
>>> rng = np.random.default_rng(0)
>>> y_true = rng.normal(size=500)
>>> qs = np.array([0.1, 0.5, 0.9])
>>> y_pred_q = np.quantile(
...     y_true[:, None] + rng.normal(scale=.1, size=(500, 3)),
...     qs, axis=1).T
>>> plot_quantile_calibration(
...     y_true, y_pred_q, qs, kind='reliability_diagram')
>>> plt.show()