kdiagram.plot.evaluation.plot_taylor_diagram

kdiagram.plot.evaluation.plot_taylor_diagram(*y_preds, reference, names=None, acov='half_circle', zero_location='W', direction=-1, only_points=False, ref_color='red', draw_ref_arc=True, angle_to_corr=True, marker='o', corr_steps=6, fig_size=None, title=None, savefig=None)

Plot a standard Taylor Diagram.

Graphically summarizes how closely a set of predictions match observations (reference). The diagram displays the correlation coefficient and standard deviation of each prediction relative to the reference data [1].

Parameters:

• *y_preds (array-like) – Variable number of 1D prediction arrays (e.g., model outputs). Each must have the same length as reference.

• reference (array-like) – 1D array of reference (observation) data. Must have the same length as each prediction array in *y_preds.

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

• acov ({'default', 'half_circle'}, default: "half_circle") –

  Determines the angular coverage (correlation range) of the plot:

  • 'default': Spans 180 degrees (\(\pi\)), covering correlations from -1 to 1 (if applicable).

  • 'half_circle': Spans 90 degrees (\(\pi/2\)), covering positive correlations from 0 to 1.

• zero_location ({'N','NE','E','S','SW','W','NW','SE'}, default: 'W') –

  Specifies the position on the polar plot corresponding to perfect correlation (\(\rho=1\), angle=0). For example, 'N' (North) is top, 'E' (East) is right, 'W' (West) is left.

  Effects:

  • Positioning: Changes the orientation of the diagram by rotating the zero-degree line.

  • Interpretation: Influences how the angular coordinates correspond to correlation values.

  Example:

  • Setting zero_location=’N’ places the zero-degree correlation at the top of the plot.

  • Setting zero_location=’E’ places it on the right side.

• direction ({1, -1}, default: -1) –

  Direction of increasing angle (decreasing correlation). 1 for counter-clockwise, -1 for clockwise.

  Effects:

  • Angle Progression: Dictates whether the angles move clockwise or counter-clockwise from the zero location.

  • Visual Interpretation: Affects the layout of the correlations on the diagram.

  Example:

  • direction=1: Correlation angles increase counter-clockwise, which might align with standard mathematical conventions.

  • direction=-1: Correlation angles increase clockwise, which might be preferred for specific visualization standards.

• only_points (bool, default: False) – If True, only plot markers for predictions. If False, also draw radial lines from the origin to each marker.

• ref_color (str, default: 'red') – Color for the reference standard deviation marker (arc or point/line). Accepts any valid matplotlib color format.

• draw_ref_arc (bool, default: True) – If True, show the reference standard deviation as an arc. If False, show as a marker/line at angle zero.

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

• marker (str, default: 'o') – Marker style for the prediction points (e.g., ‘o’, ‘s’, ‘^’).

• corr_steps (int, default: 6) – Number of ticks (intervals) between 0 and 1 correlation when angle_to_corr is True.

• fig_size (tuple of (float, float), optional) – Figure size in inches (width, height). If None, defaults to (10, 8).

• title (str, optional) – Title for the diagram. If None, defaults to “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 implementation may need `return ax` added.)

Return type:

matplotlib.axes.Axes

Raises:

• ValueError – If input arrays have inconsistent lengths or if invalid parameter options are provided for acov, zero_location, or direction.

• AssertionError – If length check inside the function fails (redundant with ValueError from decorator likely).

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

Notes

Taylor diagrams visually assess model performance relative to observations based on three statistics: the correlation coefficient (\(R\)), the standard deviation (\(\sigma\)), and the centered root-mean-square difference (RMSD).

The relationship is based on the law of cosines: .. math:

RMSD^2 = \sigma_p^2 + \sigma_r^2 - 2\sigma_p \sigma_r R

where \(\sigma_p\) and \(\sigma_r\) are the standard deviations of the prediction and reference, respectively.

On the diagram:

• Radial distance = Standard deviation (\(\sigma_p\))

• Angle = Correlation (\(\arccos(R)\))

• Distance to reference point = Centered RMSD

See also

numpy.corrcoef

Compute correlation coefficients.

numpy.std

Compute standard deviation.

kdiagram.plot.evaluation.taylor_diagram

Flexible version.

kdiagram.plot.evaluation.plot_taylor_diagram_in

Version with 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
>>> np.random.seed(101)
>>> reference = np.random.normal(0, 1.0, 100)
>>> y_preds = [
...     reference * 0.8 + np.random.normal(0, 0.4, 100), # Model A
...     reference * 0.5 + np.random.normal(0, 1.1, 100)  # Model B
... ]
>>> # ax = plot_taylor_diagram( # Capture axis if returned
>>> plot_taylor_diagram(
...     *y_preds,
...     reference=reference,
...     names=['Model A', 'Model B'],
...     acov='half_circle',
...     zero_location='W', # Corr=1 on West axis
...     fig_size=(9, 7)
... )