kdiagram.plot.errors.plot_error_violins

kdiagram.plot.errors.plot_error_violins(df, *error_cols, names=None, title=None, figsize=(9.0, 9.0), cmap='viridis', show_grid=True, grid_props=None, savefig=None, dpi=300, acov='default', ax=None, **violin_kws)[source]

Plot polar violin plots to compare multiple error distributions.

This function creates a polar plot where each angular sector contains a violin plot representing the error distribution of a different model or dataset. It is a powerful tool for visually comparing bias, variance, and the overall shape of error distributions [1].

Parameters:
dfpd.DataFrame

The input DataFrame containing the error data.

*error_colsstr

One or more column names from df, each containing the error values (e.g., actual - predicted) for a model to be plotted.

nameslist of str, optional

Display names for each of the models corresponding to error_cols. If not provided, generic names like 'Model 1' will be generated. The list length must match the number of error columns.

titlestr, optional

The title for the plot. If None, a default is generated.

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

Figure size in inches.

cmapstr, default=’viridis’

Matplotlib colormap used to assign a unique color to each violin plot.

show_gridbool, default=True

Toggle gridlines via the package helper set_axis_grid.

grid_propsdict, optional

Keyword arguments passed to set_axis_grid for grid customization.

savefigstr, optional

If provided, save the figure to this path; otherwise the plot is shown interactively.

dpiint, default=300

Resolution for the saved figure.

**violin_kwsdict, optional

Additional keyword arguments passed to the ax.fill call for each violin (e.g., alpha, edgecolor).

Returns:
axmatplotlib.axes.Axes or None

The Matplotlib Axes object containing the plot, or None if the plot could not be generated.

Parameters:

Notes

The plot visualizes and compares several one-dimensional error distributions. It adapts the standard violin plot [1] to a polar coordinate system for multi-model comparison.

  1. Kernel Density Estimation (KDE): For each model’s error data \(\mathbf{x} = \{x_1, x_2, ..., x_n\}\), the probability density function (PDF), \(\hat{f}_h(x)\), is estimated using a Gaussian kernel. This creates a smooth curve representing the distribution’s shape.

    (1)\[\hat{f}_h(x) = \frac{1}{nh} \sum_{i=1}^{n} K\left(\frac{x - x_i}{h}\right)\]

    where \(K\) is the Gaussian kernel and \(h\) is the bandwidth, a smoothing parameter.

  2. Violin Construction: The violin shape is created by plotting the density curve \(\hat{f}_h(x)\) symmetrically around a central axis. The width of the violin at any given error value \(x\) is proportional to its estimated density.

  3. Polar Arrangement: Each model’s violin is assigned a unique angular sector on the polar plot. The radial axis represents the error value, with a reference circle at \(r=0\) indicating a perfect forecast. The violin is drawn radially within its assigned sector.

References

[1] (1,2)

Hintze, J. L., & Nelson, R. D. (1998). Violin Plots: A Box Plot-Density Trace Synergism. The American Statistician, 52(2), 181-184.

Examples

>>> import numpy as np
>>> import pandas as pd
>>> from kdiagram.plot.errors import plot_polar_error_violins
>>>
>>> # Simulate errors from three different models
>>> np.random.seed(0)
>>> n_points = 1000
>>> df_errors = pd.DataFrame({
...     'Model A (Good)': np.random.normal(
...           loc=0.5, scale=1.5, size=n_points),
...     'Model B (Biased)': np.random.normal(
...           loc=-4.0, scale=1.5, size=n_points),
...     'Model C (Inconsistent)': np.random.normal(
...           loc=0, scale=4.0, size=n_points),
... })
>>>
>>> # Generate the polar violin plot
>>> ax = plot_polar_error_violins(
...     df_errors,
...     'Model A (Good)',
...     'Model B (Biased)',
...     'Model C (Inconsistent)',
...     title='Comparison of Model Error Distributions',
...     cmap='plasma',
...     alpha=0.7
... )