kdiagram.plot.evaluation.plot_polar_roc

kdiagram.plot.evaluation.plot_polar_roc(y_true, *y_preds, names=None, title='Polar ROC Curve', figsize=(8, 8), cmap='tab10', colors=None, show_grid=True, grid_props=None, acov='quarter_circle', fill_alpha=0.15, show_no_skill=True, show_auc=True, savefig=None, dpi=300, kind='polar', ax=None)[source]

Plots a Polar Receiver Operating Characteristic (ROC) Curve.

This function visualizes the performance of binary classification models by mapping the standard ROC curve onto a polar plot. It is a novel visualization developed as part of the analytics framework in [1].

Parameters:
y_truearray_like of shape (n_samples,)

Ground-truth binary labels (0/1). Values are validated and flattened. If labels are not in {0, 1}, they will be cast to integers after validation.

*y_predsarray_like of shape (n_samples,), required

One or more arrays of predicted scores or probabilities for the positive class. Each array is validated against y_true and flattened. At least one prediction vector must be provided.

nameslist of str or None, default=None

Display names for the prediction series. When None, generic names such as "Model 1", "Model 2", … are generated. If provided but the length differs from the number of series, a warning is issued and generic names are used.

titlestr, default=”Polar ROC Curve”

Figure title.

figsizetuple of float, default=(8, 8)

Figure size in inches.

cmapstr, default=”viridis”

Matplotlib colormap used to assign distinct colors to the curves.

show_gridbool, default=True

Whether to display polar grid lines. Styling can be tuned through grid_props.

grid_propsdict or None, default=None

Keyword arguments forwarded to the internal grid helper to adjust grid line style (e.g., {"linestyle": "--", "alpha": 0.5}).

acov{“quarter_circle”, …}, default=”quarter_circle”

Angular coverage request. For this release it is accepted only for compatibility; any value other than ``”quarter_circle”`` causes a warning and the plot is reset to a 0–90° span with θ=0 at East.

fill_alphafloat, default=0.15

Opacity used to fill the area under each ROC curve.

show_no_skillbool, default=True

If True, draws the baseline no-skill curve (TPR = FPR) as a dashed line.

show_aucbool, default=True

If True, appends the numerical AUC value to each legend label.

savefigstr or None, default=None

When a path is given, the figure is saved to that location (directory must exist). If None, the figure is shown.

dpiint, default=300

Resolution used when saving the figure.

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)

axmatplotlib.axes.Axes or None, default=None

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

Returns:
axmatplotlib.axes.Axes

The polar axes containing the ROC visualization. This can be used for further customization.

Parameters:

See also

plot_polar_pr_curve

A companion plot for precision-recall.

sklearn.metrics.roc_curve

The underlying scikit-learn function.

Notes

A Receiver Operating Characteristic (ROC) curve is a standard tool for evaluating binary classifiers [2]. It plots the True Positive Rate (TPR) against the False Positive Rate (FPR) at various threshold settings.

(1)\[\text{TPR} = \frac{TP}{TP + FN} \quad , \quad \text{FPR} = \frac{FP}{FP + TN}\]

This function adapts the concept to a polar plot:

  • The angle (θ) is mapped to the False Positive Rate, spanning from 0 at 0° to 1 at 90°.

  • The radius (r) is mapped to the True Positive Rate, spanning from 0 at the center to 1 at the edge.

A model with no skill (random guessing) is represented by a perfect Archimedean spiral. A good model will have a curve that bows outwards, maximizing the area under the curve (AUC).

the plot is always rendered as a quarter circle (0–90°) with θ=0 placed at the East (right) of the plot. Passing any value for acov other than "quarter_circle" will emit a warning and the setting will be reset to a quarter circle. This layout yields the clearest reading of FPR (angle) versus TPR (radius) for ROC.

References

Examples

>>> import numpy as np
>>> from sklearn.datasets import make_classification
>>> from kdiagram.plot.evaluation import plot_polar_roc
>>>
>>> # Generate synthetic binary classification data
>>> X, y_true = make_classification(
...     n_samples=500, n_classes=2, random_state=42
... )
>>>
>>> # Simulate predictions from two models
>>> y_pred_good = y_true * 0.7 + np.random.rand(500) * 0.3
>>> y_pred_bad = np.random.rand(500)
>>>
>>> # Generate the plot
>>> ax = plot_polar_roc(
...     y_true,
...     y_pred_good,
...     y_pred_bad,
...     names=["Good Model", "Random Model"]
... )