kdiagram.plot.taylor_diagram.plot_taylor_diagram

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

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_predsarray_like

Variable number of 1D prediction arrays (e.g., model outputs). Each must have the same length as reference.

referencearray_like

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

nameslist 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_pointsbool, default: False

If True, only plot markers for predictions. If False, also draw radial lines from the origin to each marker.

ref_colorstr, default: ‘red’

Color for the reference standard deviation marker (arc or point/line). Accepts any valid matplotlib color format.

draw_ref_arcbool, default: True

If True, show the reference standard deviation as an arc. If False, show as a marker/line at angle zero.

angle_to_corrbool, default: True

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

markerstr, default: ‘o’

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

corr_stepsint, default: 6

Number of ticks (intervals) between 0 and 1 correlation when angle_to_corr is True.

fig_sizetuple of (float, float), optional

Figure size in inches (width, height). If None, defaults to (10, 8).

titlestr, optional

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

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.

Parameters:

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.

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:

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

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