kdiagram.plot.evaluation.plot_taylor_diagram_in

kdiagram.plot.evaluation.plot_taylor_diagram_in(*y_preds, reference, names=None, acov=None, zero_location='E', direction=-1, only_points=False, ref_color='red', draw_ref_arc=True, angle_to_corr=True, marker='o', corr_steps=6, cmap='viridis', shading='auto', shading_res=300, radial_strategy=None, norm_c=False, norm_range=None, cbar='off', fig_size=None, title=None, savefig=None)

Plot Taylor Diagram with background color map.

Generates a Taylor Diagram comparing predictions to a reference, featuring a background color map encoding correlation or other metrics based on the chosen strategy.

The diagram uses polar coordinates where the radial axis represents the standard deviation (\(\sigma_p\)) of each prediction, and the angular axis represents the correlation (\(\rho\)) with the reference, typically via the angle \(\theta = \arccos(\rho)\).

Parameters:

• *y_preds (array-like) – One or more 1D prediction arrays (e.g., model outputs). Each array must have the same length as reference. Multi-dimensional inputs are flattened internally.

• reference (array-like) – The 1D reference (observed) array of shape \((n,)\). Must have the same length as each array in *y_preds.

• names (list of str or None, optional) – Labels for each prediction array in *y_preds. Must match the number of predictions if provided. If None, defaults like “Pred 1”, “Pred 2” are used.

• acov ({'default', 'half_circle'}, optional) –

  Angular coverage of the diagram:

  • 'default': Spans \(\pi\) (180 degrees).

  • 'half_circle': Spans \(\pi/2\) (90 degrees).

  If None, defaults to 'half_circle'.

• zero_location ({'N','NE','E','S','SW','W','NW','SE'}, optional) – Position corresponding to perfect correlation (\(\rho=1\)). Default is 'E'.

• direction (int, optional) – Rotation direction for increasing angles (correlation). 1 for counter-clockwise, -1 for clockwise. Default is -1.

• only_points (bool, optional) – If True, plot only markers for predictions, omitting radial lines from the origin. Default is False.

• ref_color (str, optional) – Color for the reference standard deviation marker (arc or line/point). Default is 'red'.

• draw_ref_arc (bool, optional) – If True (default), draw reference std dev as an arc. If False, draw as a radial line/point at angle zero.

• angle_to_corr (bool, optional) – If True (default), label the angular axis with correlation values (\(\rho\)). If False, label with degrees.

• marker (str, optional) – Marker style for prediction points (e.g., ‘o’, ‘^’, ‘s’). Default is 'o'.

• corr_steps (int, optional) – Number of correlation ticks (0 to 1) when angle_to_corr is True. Default is 6.

• cmap (str, optional) – Colormap name for the background mesh (e.g., ‘viridis’). Default is 'viridis'.

• shading ({'auto', 'gouraud', 'nearest'}, optional) – Shading method for the background mesh (pcolormesh). Default is 'auto'.

• shading_res (int, optional) – Resolution for the background mesh grid. Default is 300.

• radial_strategy ({'convergence', 'norm_r', 'performance'}, optional) –

  Strategy for calculating background color values:

  • 'convergence': Color maps to correlation \(\cos(\theta)\).

  • 'norm_r': Color maps to normalized radius (std dev).

  • 'performance': Color highlights region near the best performing input model.

  If None, defaults to 'performance'. ‘rwf’ and ‘center_focus’ are not supported here.

• norm_c (bool, optional) – If True, normalize background color values using norm_range. Default is False.

• norm_range (tuple of (float, float), optional) – Range (min, max) for background color normalization when norm_c is True. Default is (0, 1).

• cbar (bool or {'off'}, optional) – Control colorbar display for the background mesh. 'off' or False hides it, True shows it. Default is 'off'.

• fig_size (tuple of (float, float), optional) – Figure size in inches (width, height). Default is (10, 8).

• title (str, optional) – Title of the diagram. Default is "Taylor Diagram".

• savefig (str or None, optional) – Path to save the figure (e.g., "diagram.png"). If None, the figure is displayed interactively. Default is None.

Returns:

ax – The Matplotlib Axes object containing the Taylor Diagram. (Note: Original code may not explicitly return ax.)

Return type:

matplotlib.axes.Axes

Raises:

• ValueError – If input arrays have inconsistent lengths or if invalid parameter options are provided (e.g., for acov, zero_location, radial_strategy).

• TypeError – If non-numeric data is encountered in input arrays.

Notes

The Taylor diagram [1] displays standard deviation (\(\sigma_p\)) and correlation (\(\rho\)) relative to a reference (\(r\)) with standard deviation \(\sigma_r\).

1. Correlation (\(\rho\)): .. math:

   \rho = \frac{\mathrm{Cov}(p, r)}{\sigma_p \sigma_r}
   

2. Standard Deviation (\(\sigma_p\)): .. math:

   \sigma_p = \sqrt{\frac{1}{n}
   \sum_{i=1}^n (p_i - \bar{p})^2}
   

The plot uses polar coordinates where radius is \(\sigma_p\) and angle is \(\theta = \arccos(\rho)\). The distance from a plotted point to the reference point represents the centered RMS difference.

See also

numpy.corrcoef

Compute correlation coefficients.

numpy.std

Compute standard deviation.

kdiagram.plot.evaluation.taylor_diagram

Flexible version accepting stats or arrays.

kdiagram.plot.evaluation.plot_taylor_diagram

Basic version without background shading.

References

[1]

Taylor, K. E. (2001). Summarizing multiple aspects of model performance in a single diagram. Journal of Geophysical Research, 106(D7), 7183-7192.

Examples

>>> import numpy as np
>>> # Assuming function is imported:
>>> # from kdiagram.plot.evaluation import plot_taylor_diagram_in
>>> np.random.seed(42)
>>> reference = np.random.normal(0, 1, 100)
>>> y_preds = [
...     reference + np.random.normal(0, 0.3, 100),
...     reference * 0.9 + np.random.normal(0, 0.8, 100)
... ]
>>> # ax = plot_taylor_diagram_in( # Capture axis if returned
>>> plot_taylor_diagram_in(
...     *y_preds,
...     reference=reference,
...     names=['Model A', 'Model B'],
...     acov='half_circle',
...     zero_location='N',
...     direction=1,
...     fig_size=(8, 8),
...     cbar=True,
...     radial_strategy='convergence'
... )
>>> # Plot is shown if savefig is None