fusionlab.plot.evaluation.plot_crps

fusionlab.plot.evaluation.plot_crps(y_true, y_pred_ensemble, crps_values=None, metric_kws=None, kind='summary_bar', sample_idx=0, output_idx=0, ecdf_color='dodgerblue', true_value_color='red', ensemble_marker_color='gray', hist_bins='auto', hist_color='skyblue', hist_edgecolor='black', figsize=(10, 6), title='Continuous Ranked Probability Score (CRPS)', xlabel=None, ylabel=None, bar_color='cornflowerblue', 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 Continuous Ranked Probability Score (CRPS) for ensemble forecasts.

Three complementary views are available:

  • ‘ensemble_ecdf’ – ECDF of a single ensemble, the true value, and the per‑instance CRPS.

  • ‘scores_histogram’ – distribution of per‑sample CRPS values.

  • ‘summary_bar’ – bar chart of the overall CRPS (or one bar 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_pred_ensemble (ndarray) – Ensemble predictions. Shape (N, M) for a single output or (N, O, M) for multiple outputs, where M is the number of ensemble members.

  • crps_values (float or ndarray, optional) – Pre‑computed CRPS value(s). If supplied, the helper skips internal calls to fusionlab.metrics.continuous_ranked_probability_score().

  • metric_kws (dict, default None) – Extra keyword arguments forwarded verbatim to the underlying metric function (e.g. coverage_score). Use this to tweak

  • kind ({'ensemble_ecdf', 'scores_histogram', 'summary_bar'},) – default 'summary_bar' Style of plot to generate.

  • sample_idx (int, default 0) – Index of the sample to display when kind='ensemble_ecdf'.

  • output_idx (int, default 0) – Output dimension to display when kind='ensemble_ecdf'.

  • ecdf_color (str, default :class:``’dodgerblue’:class:``)

  • true_value_color (str, default :class:``’red’:class:``)

  • ensemble_marker_color (str, default :class:``’gray’:class:``) – Styling parameters for the ECDF plot.

  • hist_bins (int | sequence | str, default :class:``’auto’:class:``)

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

  • hist_edgecolor (str, default :class:``’black’:class:``) – Histogram styling parameters.

  • 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) – Append the numeric CRPS to the title (where applicable).

  • 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 CRPS visualisation.

Return type:

matplotlib.axes.Axes

Notes

For one observation with ensemble members \(x_1,\dots,x_M\) and true value \(y\), the sample‑based CRPS is

\[\operatorname{CRPS} \;=\; \frac{1}{M}\sum_{j=1}^M |x_j - y| \;-\;\frac{1}{2M^2}\sum_{i=1}^M\sum_{j=1}^M |x_i - x_j|.\]

Lower scores indicate sharper and better‑calibrated probabilistic forecasts.

Examples

>>> import numpy as np, matplotlib.pyplot as plt
>>> from fusionlab.plot.evaluation import plot_crps
>>> rng = np.random.default_rng(0)
>>> y_true = rng.normal(size=500)
>>> ens     = y_true[:, None] + rng.normal(scale=.5, size=(500, 20))
>>> plot_crps(y_true, ens, kind='scores_histogram')
>>> plt.show()

See also

fusionlab.metrics.continuous_ranked_probability_score

Numeric computation of sample‑based CRPS.

fusionlab.plot.evaluation.plot_quantile_calibration

Reliability diagrams for quantile forecasts.

fusionlab.plot.evaluation.plot_weighted_interval_score

Interval‑based sharpness and calibration plot.

References