kdiagram.plot.comparison.plot_polar_reliability

kdiagram.plot.comparison.plot_polar_reliability(y_true, *y_preds, names=None, n_bins=10, strategy='uniform', title='Polar Reliability Diagram', figsize=(8.0, 8.0), cmap='coolwarm', acov='half_circle', show_grid=True, grid_props=None, show_cbar=True, mask_radius=False, savefig=None, dpi=300, ax=None)

Plot a Polar Reliability Diagram (Calibration Spiral).

This function provides a novel visualization of model calibration by mapping the traditional reliability diagram onto a polar coordinate system [1]. It compares predicted probabilities (mapped to the angle) to observed frequencies (mapped to the radius).

Perfect calibration is represented by a perfect Archimedean spiral. The plot uses a diverging colormap to diagnostically color the model’s spiral, immediately revealing regions of over- or under-confidence.

Parameters:

y_truenp.ndarray

1D array of true binary labels (0 or 1).

*y_predsnp.ndarray

One or more 1D arrays of predicted probabilities for each model.

nameslist of str, optional

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

n_binsint, default=10

Number of bins to group predicted probabilities into for analysis.

strategy{‘uniform’, ‘quantile’}, default=’uniform’

The strategy for creating bins:

• 'uniform': Bins are of equal width across the [0, 1] range.

• 'quantile': Bins are created based on the quantiles of the predicted probabilities, ensuring each bin has a similar number of samples.

titlestr, default=”Polar Reliability Diagram”

The title for the plot.

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

The figure size in inches.

cmapstr, default=’coolwarm’

A diverging colormap used to color the model’s spiral. The center of the colormap represents perfect calibration, with one color for over-confidence and another for under-confidence.

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

‘eighth_circle’}, default=’half_circle’ 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_cbarbool, default=True

If True, display a color bar that explains the diagnostic coloring of the calibration error.

show_gridbool, default=True

Toggle the visibility of the polar grid lines.

grid_propsdict, optional

Custom keyword arguments passed to the grid for styling (e.g., linestyle, alpha).

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 polar reliability plot.

Parameters:

• y_true (ndarray)

• y_preds (ndarray)

• names (list[str] | None)

• n_bins (int)

• strategy (str)

• title (str)

• figsize (tuple[float, float])

• cmap (str)

• acov (Literal['default', 'half_circle', 'quarter_circle', 'eighth_circle'])

• show_grid (bool)

• grid_props (dict[str, Any] | None)

• show_cbar (bool)

• mask_radius (bool)

• savefig (str | None)

• dpi (int)

• ax (Axes | None)

Return type:

Axes

Notes

This plot is a polar adaptation of the standard reliability diagram, a key tool in forecast verification [2].

1. Binning: Predicted probabilities \(p_i\) are first partitioned into \(K\) bins. For each bin \(k\), the mean predicted probability (\(\bar{p}_k\)) and the mean observed frequency (\(\bar{y}_k\)) are calculated.

2. Polar Mapping: These values are then mapped to polar coordinates:

   (1)\[\begin{split}\theta_k &= \bar{p}_k \cdot \frac{\pi}{2} \\ r_k &= \bar{y}_k\end{split}\]

   The plot is constrained to a 90-degree quadrant where the angle \(\theta\) represents the predicted probability from 0 to 1, and the radius \(r\) represents the observed frequency from 0 to 1.

3. Perfect Calibration: A perfectly calibrated model, where \(\bar{p}_k = \bar{y}_k\) for all bins, will form a perfect Archimedean spiral defined by \(r = \frac{2\theta}{\pi}\). This is drawn as a dashed black reference line.

4. Diagnostic Coloring: The calibration error for each bin is calculated as \(e_k = \bar{y}_k - \bar{p}_k\). The line segments of the model’s spiral are colored based on this error:

   • \(e_k < 0\): The model is over-confident (observed frequency is lower than predicted probability).

   • \(e_k > 0\): The model is under-confident (observed frequency is higher than predicted probability).

References

[1]

Kouao Laurent Kouadio. k-diagram: technical report — derivations and details. Technical Report, School of Geosciences and Info-physics, Central South University, Sep 2025. Software technical report accompanying the k-diagram package. URL: https://doi.org/10.5281/zenodo.17051183, doi:10.5281/zenodo.17051183.

[2]

Ian T. Jolliffe and David B. Stephenson. Forecast Verification: A Practitioner’s Guide in Atmospheric Science. Wiley, 2012. ISBN 9781119960003. doi:10.1002/9781119960003.

Examples

>>> import numpy as np
>>> from kdiagram.plot.comparison import plot_polar_reliability
>>>
>>> # Generate synthetic data for two models
>>> np.random.seed(0)
>>> n_samples = 2000
>>> y_true = (np.random.rand(n_samples) < 0.4).astype(int)
>>> # A well-calibrated model
>>> calibrated_preds = np.clip(0.4 + np.random.normal(0, 0.15, n_samples), 0, 1)
>>> # An over-confident model
>>> overconfident_preds = np.clip(0.4 + np.random.normal(0, 0.3, n_samples), 0, 1)
>>>
>>> # Generate the plot
>>> ax = plot_polar_reliability(
...     y_true,
...     calibrated_preds,
...     overconfident_preds,
...     names=["Well-Calibrated", "Over-Confident"],
...     n_bins=15,
...     cmap='coolwarm'
... )