fusionlab.plot.evaluation.plot_theils_u_score¶

fusionlab.plot.evaluation.plot_theils_u_score(y_true, y_pred, metric_values=None, metric_kws=None, kind='summary_bar', figsize=(8, 6), title="Theil's U Statistic", ylabel=None, bar_color='chocolate', bar_width=0.8, score_annotation_format='{:.4f}', reference_line_at_1=True, reference_line_props=None, show_grid=True, grid_props=None, ax=None, verbose=0, **kwargs)[source]¶

Visualise Theil’s U statistic.

A single‑bar (or multi‑bar) summary plot that benchmarks a model’s error against a naïve “last‑value’’ forecast. U < 1 implies the model improves upon the naïve baseline; U = 1 indicates parity; U > 1 denotes under‑performance.

Parameters:

y_true (ndarray of shape (n_samples, …)) – Ground‑truth target values. Depending on the metric a 1‑D array (global aggregation), a 2‑D array (n_samples, n_outputs), or a 3‑D array (n_samples, n_horizons, n_outputs) may be
y_pred (ndarray) – Point‑forecast predictions with the same shape semantics as y_true. Used by deterministic metrics such as MAE or RMSE as
metric_values (float or ndarray, optional) – Pre‑computed Theil’s U statistic(s). When supplied the helper skips internal evaluation and plots the given number(s) verbatim.
metric_kws (dict, optional) – Additional keyword arguments forwarded to fusionlab.metrics.theils_u_score() (e.g. multioutput='raw_values').
kind ({'summary_bar'}, default :class:``’summary_bar’:class:``) – Currently only a bar‑chart summary is available. Additional kinds may be added in future releases.
reference_line_at_1 (bool, default True) – Draw a horizontal reference line at U = 1 to highlight the naïve‑benchmark threshold.
reference_line_props (dict, optional) – Matplotlib style overrides for the reference line (colour, linestyle, linewidth …).
figsize (tuple of float, optional) – Size of the figure in inches (width, height). If omitted the
title (str, optional) – Main title for the figure. If None, a context‑aware default
ylabel (str, optional) – Label for the y‑axis. If None, a context‑sensitive default is
bar_color (str or list of str, optional) – Bar face‑colour(s). Accepts any Matplotlib‑recognised colour
bar_width (float, default 0.8)
score_annotation_format (str, default '{:.4f}') – Python format string used for numeric annotations. Examples:
show_grid (bool, default True)
grid_props (dict, optional) – Keyword arguments forwarded to Axes.grid for fine‑grained
ax (matplotlib.axes.Axes, optional) – Existing Matplotlib axes to draw on. If None, a new figure
verbose (int, default 0) – Verbosity level. 0 ⇒ silent, 1 ⇒ basic info, 2+ ⇒ debug
**kwargs – Additional keyword arguments passed directly to the underlying Matplotlib primitives (plot, scatter, bar,

Returns:

The axes object with the rendered plot.

Return type:

matplotlib.axes.Axes

Notes

For a univariate series the statistic is

\[U = \sqrt{\frac{\sum_{t=2}^{T} \bigl(y_t - \hat y_t\bigr)^2} {\sum_{t=2}^{T} \bigl(y_t - y_{t-1}\bigr)^2}}\]

where \(y_{t-1}\) is the naïve forecast. The helper calls fusionlab.metrics.theils_u_score() for the computation.

Examples

>>> import numpy as np, matplotlib.pyplot as plt
>>> from fusionlab.plot.evaluation import plot_theils_u_score
>>> rng = np.random.default_rng(0)
>>> y_true = rng.normal(size=100)
>>> y_pred = y_true + rng.normal(scale=.2, size=100)
>>> plot_theils_u_score(y_true, y_pred,
...                     bar_color='steelblue',
...                     figsize=(6, 4))
>>> plt.show()