fusionlab.plot.evaluation.plot_time_weighted_metric¶

fusionlab.plot.evaluation.plot_time_weighted_metric(metric_type, y_true, y_pred=None, y_median=None, y_lower=None, y_upper=None, alphas=None, time_weights='inverse_time', metric_values=None, metric_kws=None, kind='summary_bar', output_idx=None, sample_idx=None, figsize=(12, 6), title=None, xlabel=None, ylabel=None, profile_line_color='royalblue', profile_line_style='-', profile_marker='o', time_weights_color='gray', show_time_weights_on_profile=False, bar_color='royalblue', bar_width=0.8, score_annotation_format='{:.4f}', show_score_on_title=True, show_grid=True, grid_props=None, ax=None, verbose=0, **kwargs)[source]¶

Visualise time‑weighted error / accuracy metrics (MAE, classification accuracy, or interval‑based scores) as either

a summary bar of the overall time‑weighted score, or one bar per output dimension; or
a time‑profile curve that shows how the metric evolves over the forecasting horizon, optionally overlaid with the weight distribution.

The helper delegates numeric computation to the corresponding metric in :pymod:`fusionlab.metrics` and applies the chosen time weights before visualisation.

Parameters:

metric_type ({'mae', 'accuracy', 'interval_score'}) –
Which metric to compute and plot. * 'mae' – Mean Absolute Error. * 'accuracy' – Classification accuracy. * 'interval_score' – Weighted interval score

(requires median, bounds, and alphas).
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
y_median (ndarray) – Median (50‑th quantile) of a probabilistic forecast. The array
y_lower (ndarray) – Lower‑bound quantile (e.g. 0.05 or 0.10) for an uncertainty interval. Shape must mirror y_true. Required by coverage,
y_upper (ndarray) – Upper‑bound quantile (e.g. 0.95 or 0.90) paired with y_lower.
alphas (1‑D ndarray) – Alpha levels α = 2 × min(q, 1−q) that define the nominal coverage (1 − α) of each prediction interval used in Weighted
time_weights (1‑D sequence, :class:``’inverse_time’:class:`` or None,) –
default 'inverse_time' * array‑like – explicit non‑negative weights for each

timestep (length T). They are automatically normalised to sum to 1.
- 'inverse_time' – use \(w_t \propto 1 / (t + 1)\) (early timesteps matter more).
- None – uniform weights (1/T).
metric_values (float or ndarray, optional) – Pre‑computed time‑weighted score(s) to plot, bypassing internal metric evaluation.
metric_kws (dict, default None) – Extra keyword arguments forwarded verbatim to the underlying metric function (e.g. coverage_score). Use this to tweak
kind ({'summary_bar', 'time_profile'}, default :class:``’summary_bar’:class:``) –
- summary_bar – bar plot of the overall score.
- time_profile – line plot of the per‑timestep metric (averaged over samples), optionally with the weight profile.
output_idx (int, optional) – Output dimension to plot when the data are multi‑output and kind='time_profile'.
sample_idx (int, default 0) – Index of the time series (row) to highlight in sample‑wise
figsize (tuple of float, optional) – {see shared parameters below}
title (str | None) – {see shared parameters below}
xlabel (str | None) – {see shared parameters below}
ylabel (str | None) – {see shared parameters below}
styling (Summary‑bar)
^^^^^^^^^^^^^^^^^^^^
profile_line_color (str, default :class:``’royalblue’:class:``)
profile_line_style (str, default :class:``’-’:class:``)
profile_marker (str or None, default :class:``’o’:class:``) – Matplotlib properties for the metric curve.
time_weights_color (str, default :class:``’gray’:class:``)
show_time_weights_on_profile (bool, default False) – If True, draws a semi‑transparent bar chart of the normalised weights on a secondary y‑axis.
styling
^^^^^^^^^^^^^^^^^^^
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:
controls (Common plot)
^^^^^^^^^^^^^^^^^^^^
figsize – Size of the figure in inches (width, height). If omitted the
show_score_on_title (bool, default True) – If True, appends the aggregated metric value to the plot
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 figure.

Return type:

matplotlib.axes.Axes

Notes

Let \(w_t\) be the normalised time weight for horizon t. For MAE the time‑weighted score is

\[\text{TW‑MAE} \;=\; \sum_{t=1}^{T} w_t \, \lvert y_t - \hat y_t\rvert .\]

Analogous definitions apply for accuracy (with the 0‑1 loss) and for the weighted interval score (using the per‑timestep WIS).

If ``kind=’time_profile’`` the helper first computes the unweighted metric value for each timestep, then applies the time_weights when plotting or when aggregating to a single title score.

Examples

>>> import numpy as np, matplotlib.pyplot as plt
>>> from fusionlab.plot.evaluation import plot_time_weighted_metric
>>> T = 24
>>> y_true = np.sin(np.linspace(0, 3*np.pi, T))
>>> y_pred = y_true + np.random.normal(0, 0.1, T)
>>> ax = plot_time_weighted_metric(
...     metric_type='mae',
...     y_true=y_true,
...     y_pred=y_pred,
...     kind='time_profile',
...     show_time_weights_on_profile=True,
...     figsize=(8, 4))
>>> plt.show()