kdiagram.plot.evaluation.plot_regression_performance

kdiagram.plot.evaluation.plot_regression_performance(y_true=None, *y_preds, names=None, metrics=None, metric_values=None, add_to_defaults=False, metric_labels=None, higher_is_better=None, norm='per_metric', global_bounds=None, min_radius=0.05, clip_to_bounds=True, title='Regression Model Performance', figsize=(8, 8), cmap='viridis', colors=None, bp_padding=1.0, acov='full', zero_at='E', clockwise=True, show_grid=True, grid_props=None, mask_radius=False, savefig=None, dpi=300, kind='polar', ax=None)[source]

Creates a Polar Performance Chart for regression models.

This function generates a grouped polar bar chart to visually compare the performance of multiple regression models across several evaluation metrics simultaneously. It provides a holistic snapshot of model strengths and weaknesses.

Parameters:
y_truenp.ndarray, optional

1D array of true observed values. Required unless metric_values is provided.

*y_predsnp.ndarray

One or more 1D arrays of predicted values from different models.

nameslist of str, optional

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

metricsstr, callable(), or list of such, optional

The metric(s) to compute. If None, defaults to ['r2', 'neg_mean_absolute_error', 'neg_root_mean_squared_error']. Can be strings recognized by scikit-learn or custom callable functions.

metric_valuesdict of {str: list of float}, optional

A dictionary of pre-calculated metric scores. Keys are the metric names and values are lists of scores, one for each model. If provided, y_true and y_preds must be None.

add_to_defaultsbool, default=False

If True, the user-provided metrics are added to the default set of metrics instead of replacing them.

metric_labelsdict, bool, or list, optional

Controls the angular axis labels.

  • dict: A mapping from original metric names to new display names (e.g., {'r2': 'R²'}).

  • False or []: Hides all angular labels.

  • None (default): Shows the original metric names.

higher_is_betterdict of {str: bool}, optional

A dictionary to explicitly specify whether a higher score is better for each metric. Keys should be metric names and values should be True (higher is better) or False (lower is better). This overrides the default behavior for both string and callable metrics.

norm{‘per_metric’, ‘global’, ‘none’}, default=’per_metric’

The strategy for normalizing raw metric scores into bar radii.

  • 'per_metric': (Default) Normalizes scores for each metric independently to the range [0, 1]. The best- performing model on a given metric gets a radius of 1, and the worst gets 0. This is best for comparing the relative performance of models.

  • 'global': Normalizes scores using fixed, absolute bounds defined in the global_bounds parameter. This is useful for comparing models against a consistent, predefined scale.

  • 'none': Plots the raw, un-normalized metric scores directly. Use with caution, as metrics with different scales can make the plot difficult to interpret.

global_boundsdict of {str: (float, float)}, optional

A dictionary providing fixed (min, max) bounds for each metric when using norm='global'. The dictionary keys should be the metric names (e.g., ‘r2’) and the values should be a tuple of the worst and best possible scores. For example, {'r2': (0.0, 1.0)}.

min_radiusfloat, default=0.02

A small minimum radius to ensure that even the worst- performing bars (with a normalized score of 0) remain slightly visible on the plot.

clip_to_boundsbool, default=True

If True and norm='global', any score that falls outside the range specified in global_bounds will be clipped to that range before normalization. If False, scores can result in radii less than 0 or greater than 1.

titlestr, default=”Regression Model Performance”

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 bars.

colorslist of str, optional

A list of custom colors for the bars. If None, the function will use the colormap specified in cmap to generate the colors.

bp_paddingfloat, default=1.0

Padding factor for the “Best Performance” ring. A value of 1.0 places the ring at the maximum radius, while smaller values decrease its size.

acovstr, default=”full”

The angular coverage for the plot. Can be one of:

  • ‘full’: 360° (default)

  • ‘half’: 180°

  • ‘quarter’: 90°

  • ‘eighth’: 45°

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

The point where θ=0 is located on the plot. Options are:

  • ‘N’: North

  • ‘E’: East

  • ‘S’: South

  • ‘W’: West

clockwisebool, default=True

If True, the plot is drawn clockwise. If False, the plot is drawn counter-clockwise.

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.

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'.").

axAxes, optional

The Matplotlib Axes object to use for plotting. If None, a new figure and axes will be created.

Returns:
axmatplotlib.axes.Axes

The Matplotlib Axes object containing the plot.

Parameters:

See also

plot_model_comparison

A similar plot using a radar chart format.

Evaluating Classification Models

The user guide for evaluation plots.

Notes

This plot provides a holistic, multi-metric view of model performance, making it easy to identify trade-offs.

  1. Score Calculation: For each model and each metric, a score is calculated. Note that for error-based metrics (like MAE or RMSE), the function uses the negated version (e.g., neg_mean_absolute_error) so that a higher score is always better [1].

  2. Normalization: To make scores comparable, the scores for each metric are independently scaled to the range [0, 1] using Min-Max normalization. A score of 1 represents the best-performing model for that metric, and a score of 0 represents the worst.

  3. Polar Mapping:

    • Each metric is assigned its own angular sector.

    • The normalized score of each model is mapped to the radius (height) of its bar within that sector.

The radial bars are colored according to the model performance, and the best and worst performance rings are shown for reference.

The “Best Performance” ring is drawn at the maximum radial distance, and the “Worst Performance” ring is drawn at the minimum distance. Each model’s performance is shown as a radial bar, with the length of the bar corresponding to the normalized score.

References

Examples

>>> import numpy as np
>>> from kdiagram.plot.evaluation import plot_regression_performance
>>>
>>> # Generate synthetic data for three models
>>> np.random.seed(0)
>>> n_samples = 200
>>> y_true = np.random.rand(n_samples) * 50
>>> y_pred_good = y_true + np.random.normal(0, 5, n_samples)
>>> y_pred_biased = y_true - 10 + np.random.normal(0, 2, n_samples)
>>>
>>> # Generate the plot with clean labels
>>> ax = plot_regression_performance(
...     y_true,
...     y_pred_good,
...     y_pred_biased,
...     names=["Good Model", "Biased Model"],
...     title="Model Performance Comparison",
...     metric_labels={
...         'r2': '$R$^2',
...         'neg_mean_absolute_error': 'MAE',
...         'neg_root_mean_squared_error': 'RMSE'
...     }
... )