kdiagram.plot.evaluation.taylor_diagram¶

kdiagram.plot.evaluation.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)[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:

stddev (list 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.
corrcoef (list 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_preds (list 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.
reference (array-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.
names (list 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_std (float, 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.
cmap (str 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_arc (bool, 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_c (bool, 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_scaling (float, optional) – When norm_c is True, the normalized background mesh can be exponentiated by this factor. Useful for adjusting contrast. Default is 1.0.
marker (str, optional) – Marker style for the points representing each prediction. Defaults to ‘o’.
ref_props (dict 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_props (dict 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.
title (str or None, optional) – Title of the figure. 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 instead of being saved.

Notes

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

Standard Deviation: .. math:

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

Correlation: \(\rho\) .. math:
```
\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.

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)