kdiagram.plot.taylor_diagram.plot_taylor_diagram_in

kdiagram.plot.taylor_diagram.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, ax=None)[source]

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

referencearray_like

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

nameslist 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'.

directionint, optional

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

only_pointsbool, optional

If True, plot only markers for predictions, omitting radial lines from the origin. Default is False.

ref_colorstr, optional

Color for the reference standard deviation marker (arc or line/point). Default is 'red'.

draw_ref_arcbool, optional

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

angle_to_corrbool, optional

If True (default), label the angular axis with correlation values (\(\rho\)). If False, label with degrees.

markerstr, optional

Marker style for prediction points (e.g., ‘o’, ‘^’, ‘s’). Default is 'o'.

corr_stepsint, optional

Number of correlation ticks (0 to 1) when angle_to_corr is True. Default is 6.

cmapstr, 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_resint, 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_cbool, 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).

cbarbool or {‘off’}, optional

Control colorbar display for the background mesh. 'off' or False hides it, True shows it. Default is 'off'.

fig_sizetuple of (float, float), optional

Figure size in inches (width, height). Default is (10, 8).

titlestr, optional

Title of the diagram. Default is "Taylor Diagram".

savefigstr or None, optional

Path to save the figure (e.g., "diagram.png"). If None, the figure is displayed interactively. Default is None.

Returns:
axmatplotlib.axes.Axes

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

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.

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.

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\)):

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

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

    (2)\[\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.

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