kdiagram.plot.probabilistic.plot_polar_sharpness

kdiagram.plot.probabilistic.plot_polar_sharpness(*y_preds_quantiles, quantiles, names=None, title='Forecast Sharpness Comparison', figsize=(8.0, 8.0), cmap='viridis', marker='o', s=100, acov='default', show_grid=True, grid_props=None, mask_radius=False, savefig=None, dpi=300, ax=None)[source]

Plots a Polar Sharpness Diagram to compare forecast precision.

This function creates a polar plot to visually compare the sharpness of one or more probabilistic forecasts. Sharpness is a measure of the concentration of the predictive distribution, typically quantified by the average width of the prediction intervals. Sharper (more precise) forecasts are represented by points closer to the center of the plot.

Parameters:
*y_preds_quantilesnp.ndarray

One or more 2D arrays of quantile forecasts. Each array corresponds to a different model, with shape (n_samples, n_quantiles).

quantilesnp.ndarray

1D array of the quantile levels corresponding to the columns of the prediction arrays.

nameslist of str, optional

Display names for each of the models. If not provided, generic names like 'Model 1' will be generated.

titlestr, default=”Forecast Sharpness Comparison”

The title for the plot.

figsizetuple of (float, float), default=(8, 8)

The figure size in inches.

cmapstr, default=’viridis’

The colormap used to assign a unique color to each model’s marker.

markerstr, default=’o’

The marker style for the points representing each model.

sint, default=100

The size of the markers.

acov{‘default’, ‘half_circle’, ‘quarter_circle’,

‘eighth_circle’}, default=’default’ Angular coverage of the polar sector.

  • 'default' : full circle, \(2\pi\) (360°)

  • 'half_circle' : \(\pi\) (180°)

  • 'quarter_circle' : \(\pi/2\) (90°)

  • 'eighth_circle' : \(\pi/4\) (45°)

show_gridbool, default=True

Toggle the visibility of the polar grid lines.

grid_propsdict, optional

Custom keyword arguments passed to the grid for styling.

mask_radiusbool, default=False

If True, hide the radial tick labels.

savefigstr, optional

The file path to save the plot. If None, the plot is displayed interactively.

dpiint, default=300

The resolution (dots per inch) for the saved figure.

Returns:
axmatplotlib.axes.Axes

The Matplotlib Axes object containing the plot.

Parameters:
Return type:

Axes

Notes

A good probabilistic forecast should be both calibrated (reliable) and as sharp as possible [1]. This diagram focuses on sharpness, which is independent of the observed outcomes.

  1. Interval Width: For each model and each observation \(i\), the width of the central prediction interval is calculated using the lowest and highest provided quantiles (\(q_{min}\) and \(q_{max}\)).

    (1)\[w_i = y_{i, q_{max}} - y_{i, q_{min}}\]

  2. Sharpness Score: The sharpness score \(S\) for each model is the average of these interval widths over all \(N\) observations. This score is used as the radial coordinate in the plot. A lower score is better.

    (2)\[S = \frac{1}{N} \sum_{i=1}^{N} w_i\]

References

Examples

>>> import numpy as np
>>> from scipy.stats import norm
>>> from kdiagram.plot.probabilistic import plot_polar_sharpness
>>>
>>> # Generate synthetic data for two models
>>> np.random.seed(0)
>>> n_samples = 500
>>> y_true = np.random.normal(loc=20, scale=5, size=n_samples)
>>> quantiles = np.linspace(0.1, 0.9, 9) # 80% interval
>>>
>>> # A sharp (precise) forecast
>>> sharp_preds = norm.ppf(
...     quantiles, loc=y_true[:, np.newaxis], scale=2
... )
>>> # A wide (less precise) forecast
>>> wide_preds = norm.ppf(
...     quantiles, loc=y_true[:, np.newaxis], scale=5
... )
>>>
>>> # Generate the plot
>>> ax = plot_polar_sharpness(
...     sharp_preds,
...     wide_preds,
...     quantiles=quantiles,
...     names=["Sharp Model", "Wide Model"]
... )