kdiagram.plot.evaluation.plot_polar_confusion_matrix

kdiagram.plot.evaluation.plot_polar_confusion_matrix(y_true, *y_preds, names=None, normalize=True, title='Polar Confusion Matrix', figsize=(8, 8), cmap='viridis', colors=None, show_grid=True, grid_props=None, mask_radius=False, savefig=None, dpi=300, acov='default', zero_at='N', clockwise=True, categories=None, kind='polar', ax=None)

Plots a Polar Confusion Matrix for binary classification.

This function creates a polar bar chart to visualize the four key components of a binary confusion matrix: True Positives (TP), False Positives (FP), True Negatives (TN), and False Negatives (FN).

Parameters:

y_truenp.ndarray

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

*y_predsnp.ndarray

One or more 1D arrays of predicted probabilities or scores for the positive class. A fixed threshold of 0.5 is applied to derive class labels.

nameslist of str, optional

Display names for the models. If not provided, generic names like 'Model 1' are generated.

normalizebool, default=True

If True, values are converted to proportions that sum to 1.0 within each model. If False, raw counts are shown.

titlestr, default=”Polar Confusion Matrix”

Title to place above the figure.

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

Figure size in inches.

cmapstr, default=’viridis’

Colormap used to assign distinct colors to the bars of each model.

show_gridbool, default=True

Toggle the polar grid. Set to False for a minimal look.

grid_propsdict, optional

Keyword arguments forwarded to the grid styling helper, e.g. {'linestyle': '--', 'alpha': 0.5}.

mask_radiusbool, default=False

If True, hide the radial tick labels to declutter the plot.

savefigstr, optional

File path where the figure is saved. If None, the plot is shown interactively.

dpiint, default=300

Resolution in dots per inch used when saving.

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

‘eighth_circle’}, default=’default’ Angular coverage (span) of the polar plot. 'default' covers 360°, 'half_circle' 180°, 'quarter_circle' 90°, and 'eighth_circle' 45°. Fewer degrees compress the four sectors into a smaller sweep.

zero_at{‘N’, ‘E’, ‘S’, ‘W’}, default=’N’

Cardinal direction where θ = 0 is placed. For example, 'E' puts zero at the right-hand side.

clockwisebool, default=True

Direction of increasing angle. True draws clockwise; False draws counter-clockwise.

categorieslist of str, optional

Custom labels for the four sectors. Must contain exactly four items. If None, uses:

['True Positive', 'False Positive',
 'True Negative', 'False Negative']

The sectors are laid out starting at θ = 0 and follow the chosen direction.

kind{‘polar’, ‘cartesian’}, default=’polar’

Rendering mode selector. When set to 'polar' (default), the plot uses a Matplotlib polar projection and applies polar-specific options (acov, zero_at, clockwise) via internal helpers. When set to 'cartesian', the function delegates to a Cartesian renderer (through maybe_delegate_cartesian), keeping names/colors/figsize/grid behavior consistent while ignoring polar- only arguments (e.g., acov, zero_at, clockwise). The return value is always the Axes actually used. The value is validated with validate_kind (case-insensitive); invalid values raise ValueError("kind must be 'polar' or 'cartesian'.").

axmatplotlib.axes.Axes, optional

Existing polar axes to draw on. If None, a new figure and polar axes are created.

Returns:

axmatplotlib.axes.Axes

The Matplotlib Axes object containing the plot.

Parameters:

• y_true (ndarray)

• y_preds (ndarray)

• names (list[str] | None)

• normalize (bool)

• title (str)

• figsize (tuple[float, float])

• cmap (str)

• colors (list[str])

• show_grid (bool)

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

• mask_radius (bool)

• savefig (str | None)

• dpi (int)

• acov (str)

• zero_at (Literal['N', 'E', 'S', 'W'])

• clockwise (bool)

• categories (list[str])

• kind (str)

• ax (Axes | None)

Return type:

Axes

See also

plot_polar_confusion_multiclass

The companion plot for multiclass problems.

sklearn.metrics.confusion_matrix

The underlying scikit-learn function.

Notes

The confusion matrix is a fundamental tool for evaluating a classifier’s performance [1]. This function maps its four components to a polar bar chart for intuitive comparison.

• True Positives (TP): Correctly predicted positive cases.

• False Positives (FP): Negative cases incorrectly predicted as positive.

• True Negatives (TN): Correctly predicted negative cases.

• False Negatives (FN): Positive cases incorrectly predicted as negative.

Each of these four categories is assigned its own angular sector, and the height (radius) of the bar in that sector represents the count or proportion of samples in that category.

References

[1]

F. Pedregosa, G. Varoquaux, A. Gramfort, V. Michel, B. Olsczewski, M. Blondel, F. Prejbal, R. Weiss, V. Dubourg, J. Vanderplas, A. Passos, D. Cournapeau, M. Brucher, M. Perrot, and É. Duchesnay. Scikit-learn: machine learning in Python. Journal of Machine Learning Research, 12:2825–2830, 2011.

Examples

>>> import numpy as np
>>> from sklearn.datasets import make_classification
>>> from kdiagram.plot.evaluation import plot_polar_confusion_matrix
>>>
>>> # Generate synthetic binary classification data
>>> X, y_true = make_classification(
...     n_samples=500, n_classes=2, flip_y=0.2, random_state=42
... )
>>>
>>> # Simulate predictions from two models
>>> y_pred1 = y_true * 0.8 + np.random.rand(500) * 0.4 # Good model
>>> y_pred2 = np.random.rand(500) # Random model
>>>
>>> # Generate the plot
>>> ax = plot_polar_confusion_matrix(
...     y_true,
...     y_pred1,
...     y_pred2,
...     names=["Good Model", "Random Model"],
...     normalize=True
... )