kdiagram.plot.taylor_diagram.taylor_diagram

kdiagram.plot.taylor_diagram.taylor_diagram(stddev=None, corrcoef=None, y_preds=None, reference=None, names=None, ref_std=1, cmap=None, draw_ref_arc=False, radial_strategy='rwf', norm_c=False, power_scaling=1.0, marker='o', ref_props=None, fig_size=None, size_props=None, title=None, savefig=None, ax=None)[source]

Plot a Taylor diagram to compare multiple predictions against a reference by visualizing their correlation and standard deviation. This function can accept either precomputed statistics (i.e. stddev and corrcoef) or the actual arrays (y_preds and reference) from which these statistics will be derived.

The radial axis represents the standard deviation (std. dev.), while the angular axis represents the correlation with the reference (with angle \(\theta = \arccos(\rho)\)).

Parameters:
stddevlist of float or None, optional

List of standard deviations for each prediction. If None, the standard deviations are computed internally from y_preds. The length of stddev should match the number of models if provided.

corrcoeflist of float or None, optional

List of correlation coefficients for each prediction against the reference. If None, these are computed internally from y_preds. Must match the length of stddev if provided.

y_predslist of array_like or None, optional

One or more prediction arrays (e.g. model outputs). Each array must share the same length as reference. Required if stddev or corrcoef is not provided.

referencearray_like or None, optional

Reference (observed) array used for computing correlation and std. dev. of predictions if stddev or corrcoef is not given. Must share length with each prediction in y_preds.

nameslist of str or None, optional

Labels for each prediction array. Must match the number of models in y_preds or in stddev/corrcoef. If None, default labels of the form “Model_i” are used.

ref_stdfloat, optional

Standard deviation of the reference if already known or desired to be set explicitly. If predictions are provided (y_preds and reference), this is computed as np.std(reference) by default.

cmapstr or None, optional

Matplotlib colormap for the background shading. If not None, a contour fill is created based on the chosen radial_strategy, visualizing different performance or weighting zones. For example, ‘viridis’ or ‘plasma’.

draw_ref_arcbool, optional

If True, an arc is drawn at the reference’s standard deviation, highlighting that radial distance. If False, a point is placed at angle 0 with radial distance ref_std. Default is False.

radial_strategy{‘rwf’, ‘convergence’, ‘center_focus’,

‘performance’}, optional

Strategy for computing the background mesh (when cmap is not None):

  • 'rwf': Radial weighting function that uses correlation and deviation distance in an exponential form.

  • 'convergence': A simple radial function of r.

  • 'center_focus': Focus on a center region in the (theta, r) space using an exponential decay from the center.

  • 'performance': Highlight the region near the best performing model (max correlation, optimal std. dev.).

norm_cbool, optional

If True, the generated background mesh is normalized to the range [0, 1] before plotting. This can highlight relative differences more clearly. Default is False.

power_scalingfloat, optional

When norm_c is True, the normalized background mesh can be exponentiated by this factor. Useful for adjusting contrast. Default is 1.0.

markerstr, optional

Marker style for the points representing each prediction. Defaults to ‘o’.

ref_propsdict or None, optional

Dictionary of reference plot properties, such as line style, color, or width. Supported keys include:

  • 'label': Legend label for the reference.

  • 'lc': Line color/style for the reference arc.

  • 'color': Color/style for the reference point.

  • 'lw': Line width.

If not given, defaults to a green line and black point.

fig_size(float, float) or None, optional

Figure size in inches, e.g. (width, height). Defaults to (8, 6).

size_propsdict or None, optional

Optional dictionary to control tick and label sizes. For instance: {'ticks': 12, 'labels': 14}. Can be used to adjust the font sizes of the radial and angular ticks and labels.

titlestr or None, optional

Title of the figure. 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 instead of being saved.

See also

numpy.std

Compute standard deviation.

numpy.corrcoef

Compute correlation coefficients.

Notes

The Taylor diagram simultaneously shows two statistics for each model prediction \(p\) compared to a reference \(r\):

  1. Standard Deviation:

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

    where \(\bar{p}\) is the mean of \(p\).

  2. Correlation: \(\rho\)

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

    where \(\mathrm{Cov}(p, r)\) is the covariance between \(p\) and \(r\), and \(\sigma_r\) is the standard deviation of \(r\).

The diagram uses polar coordinates with radius corresponding to the standard deviation, and the angle \(\theta = \arccos(\rho)\) representing correlation.

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 taylor_diagram
>>> # Generate synthetic data
>>> ref = np.random.randn(100)
>>> preds = [
...     ref + 0.1 * np.random.randn(100),
...     1.2 * ref + 0.5 * np.random.randn(100),
... ]
>>> # Basic usage (auto-compute stddev and corrcoef)
>>> taylor_diagram(y_preds=preds, reference=ref)