kdiagram.plot.relationship.plot_relationship

kdiagram.plot.relationship.plot_relationship(y_true, *y_preds, names=None, title=None, theta_offset=0, theta_scale='proportional', acov='default', figsize=None, cmap='tab10', s=50, alpha=0.7, legend=True, show_grid=True, grid_props=None, color_palette=None, xlabel=None, ylabel=None, z_values=None, z_label=None, savefig=None)[source]

Visualize the relationship between y_true and multiple y_preds using a circular or polar plot. The function allows flexible configurations such as angular coverage, z-values for replacing angle labels, and customizable axis labels.

Parameters:

  • y_true (array-like) – The true values. Must be numeric, one-dimensional, and of the same length as the values in y_preds.

  • y_preds (array-like (one or more)) – Predicted values from one or more models. Each y_pred must have the same length as y_true.

  • names (list of str, optional) – A list of model names corresponding to each y_pred. If not provided or if fewer names than predictions are given, the function assigns default names as "Model_1", "Model_2", etc. For instance, if y_preds has three predictions and names is [“SVC”, “RF”], the names will be updated to [“SVC”, “RF”, “Model_3”].

  • title (str, optional) – The title of the plot. If None, the title defaults to “Relationship Visualization”.

  • theta_offset (float, default 0) – Angular offset in radians to rotate the plot. This allows customization of the orientation of the plot.

  • theta_scale ({'proportional', 'uniform'}, default 'proportional') –

    Determines how y_true values are mapped to angular coordinates (theta): - 'proportional': Maps y_true proportionally to the

    angular range (e.g., 0 to 360° or a subset defined by acov).

    • 'uniform': Distributes y_true values uniformly around the angular range.

  • acov ({'default', 'half_circle', 'quarter_circle', 'eighth_circle'},) – default=’default’ Specifies the angular coverage of the plot: - 'default': Full circle (360°). - 'half_circle': Half circle (180°). - 'quarter_circle': Quarter circle (90°). - 'eighth_circle': Eighth circle (45°). The angular span is automatically restricted to the selected portion of the circle.

  • figsize (tuple of float, default (8, 8)) – The dimensions of the figure in inches.

  • cmap (str, default 'viridis') – Colormap for the scatter points. Refer to Matplotlib documentation for a list of supported colormaps.

  • s (float, default 50) – Size of scatter points representing predictions.

  • alpha (float, default 0.7) – Transparency level for scatter points. Valid values range from 0 (completely transparent) to 1 (fully opaque).

  • legend (bool, default True) – Whether to display a legend indicating the model names.

  • show_grid (bool, default True) – Whether to display a grid on the polar plot.

  • color_palette (list of str, optional) – A list of colors to use for the scatter points. If not provided, the default Matplotlib color palette (tab10) is used.

  • xlabel (str, optional) – Label for the radial axis (distance from the center). Defaults to “Normalized Predictions (r)”.

  • ylabel (str, optional) – Label for the angular axis (theta values). Defaults to “Angular Mapping (θ)”.

  • z_values (array-like, optional) – Optional values to replace the angular labels. The length of z_values must match the length of y_true. If provided, the angular labels are replaced by the scaled z_values.

  • z_label (str, optional) – Label for the z_values, if provided. Defaults to None.

Notes

The function dynamically maps y_true to angular coordinates based on the theta_scale and acov parameters [1]. The y_preds are normalized to radial coordinates between 0 and 1[2]_. Optionally, z_values can replace angular labels with custom values [3].

\[\begin{split}\theta = \begin{cases} \text{Proportional mapping: } \theta_i = \frac{y_{\text{true}_i} - \min(y_{\text{true}})} {\max(y_{\text{true}}) - \min(y_{\text{true}})} \cdot \text{angular_range} \\ \text{Uniform mapping: } \theta_i = \frac{i}{N-1} \cdot \text{angular_range} \end{cases}\end{split}\]

Radial normalization:

\[r_i = \frac{y_{\text{pred}_i} - \min(y_{\text{pred}})} {\max(y_{\text{pred}}) - \min(y_{\text{pred}})}\]

Examples

>>> from kdiagram.plot.relationship import plot_relationship
>>> import numpy as np

# Create sample data >>> y_true = np.random.rand(100) >>> y_pred1 = y_true + np.random.normal(0, 0.1, size=100) >>> y_pred2 = y_true + np.random.normal(0, 0.2, size=100)

# Full circle visualization >>> plot_relationship( … y_true, y_pred1, y_pred2, … names=[“Model A”, “Model B”], … acov=”default”, … title=”Full Circle Visualization” … )

# Half-circle visualization with z-values >>> z_values = np.linspace(0, 100, len(y_true)) >>> plot_relationship( … y_true, y_pred1, … names=[“Model A”], … acov=”half_circle”, … z_values=z_values, … xlabel=”Predicted Values”, … ylabel=”Custom Angles” … )

See also

matplotlib.pyplot.polar

Polar plotting in Matplotlib.

numpy.linspace

Uniformly spaced numbers.

References