kdiagram.plot.evaluation.plot_polar_pr_curve

kdiagram.plot.evaluation.plot_polar_pr_curve(y_true, *y_preds, names=None, title='Polar Precision-Recall Curve', figsize=(8, 8), cmap='viridis', colors=None, show_grid=True, grid_props=None, acov='quarter_circle', fill_alpha=0.15, show_no_skill=True, show_ap=True, savefig=None, dpi=300, kind='polar', ax=None)

Plots a Polar Precision-Recall (PR) Curve.

This function visualizes the performance of binary classification models by mapping the standard PR curve onto a polar plot. It is particularly useful for evaluating models on imbalanced datasets where ROC curves can be misleading.

Parameters:

y_truendarray of shape (n_samples,)

Ground-truth binary labels in {0, 1}. Values are cast to 1D and validated against the first prediction.

*y_predsarray_like of shape (n_samples,), optional

One or more score/probability arrays for the positive class. Each must be 1D, numeric, and the same length as y_true.

nameslist of str, optional

Display names for each model. If not given or length does not match y_preds, generic labels like “Model 1” are used.

titlestr, default=”Polar Precision-Recall Curve”

Title displayed above the plot.

figsize(float, float), default=(8, 8)

Figure size in inches passed to Matplotlib.

cmapstr, default=”viridis”

Colormap name used to assign distinct colors to curves. Any valid Matplotlib colormap string is accepted.

show_gridbool, default=True

Whether to draw the polar grid (spokes and rings).

grid_propsdict, optional

Styling for the grid. For example:

{“linestyle”: “–”, “linewidth”: 0.6, “alpha”: 0.6}.

Passed to the internal grid helper.

acov{“quarter_circle”, “half_circle”, “default”,

“full”, “full_circle”, “eighth_circle”}, default=”quarter_circle”

Requested angular coverage. For PR, the plot is fixed to a quarter circle (0–90°) with θ=0 at the right. If a different value is provided, a warning is issued and the quarter-circle layout is used.

fill_alphafloat, default=0.15

Opacity of the area fill under each PR curve. Must be in [0, 1].

show_no_skillbool, default=True

If True, draws a dashed reference at the positive class prevalence and labels it as the no-skill baseline.

show_apbool, default=True

If True, appends “AP = …” to each curve label using the average precision of that model.

savefigstr or path-like, optional

Path to write the figure. If None, the figure is shown instead.

dpiint, default=300

Resolution (dots per inch) 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) 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.

axmatplotlib.axes.Axes, optional

Existing polar Axes to draw into. 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)

• title (str)

• figsize (tuple[float, float])

• cmap (str)

• colors (list[str])

• show_grid (bool)

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

• acov (str)

• fill_alpha (float)

• show_no_skill (bool)

• show_ap (bool)

• savefig (str | None)

• dpi (int)

• kind (str)

• ax (Axes | None)

Return type:

Axes

See also

plot_polar_roc

A companion plot for ROC analysis.

sklearn.metrics.precision_recall_curve

The underlying scikit-learn function.

Notes

A Precision-Recall (PR) curve is a standard tool for evaluating binary classifiers, especially on imbalanced data [1]. It plots Precision against Recall at various threshold settings.

(1)\[\text{Precision} = \frac{TP}{TP + FP} \quad , \quad \text{Recall} = \frac{TP}{TP + FN}\]

This function adapts the concept to a polar plot:

• The angle (θ) is mapped to Recall, spanning from 0 at 0° to 1 at 90°.

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

A “no-skill” classifier, which predicts randomly based on the class distribution, is represented by a horizontal line (a circle in polar coordinates) at a radius equal to the proportion of positive samples. A good model will have a curve that bows outwards towards the top-right corner of the plot, maximizing the area under the curve (Average Precision).

References

[1]

David M. W. Powers. Evaluation: from precision, recall and f-measure to roc, informedness, markedness and correlation. International Journal of Machine Learning Technology, 2(1):37–63, 2011. URL: https://arxiv.org/abs/2010.16061, doi:10.48550/arXiv.2010.16061.

Examples

>>> import numpy as np
>>> from sklearn.datasets import make_classification
>>> from kdiagram.plot.evaluation import plot_polar_pr_curve
>>>
>>> # Generate imbalanced binary classification data
>>> X, y_true = make_classification(
...     n_samples=1000,
...     n_classes=2,
...     weights=[0.9, 0.1], # 10% positive class
...     flip_y=0.1,
...     random_state=42
... )
>>>
>>> # Simulate predictions from two models
>>> y_pred_good = y_true * 0.6 + np.random.rand(1000) * 0.4
>>> y_pred_bad = np.random.rand(1000)
>>>
>>> # Generate the plot
>>> ax = plot_polar_pr_curve(
...     y_true,
...     y_pred_good,
...     y_pred_bad,
...     names=["Good Model", "Random Model"]
... )