fusionlab.metrics.time_weighted_mean_absolute_error¶

fusionlab.metrics.time_weighted_mean_absolute_error(y_true, y_pred, time_weights='inverse_time', sample_weight=None, nan_policy='propagate', multioutput='uniform_average', verbose=0)[source]¶

Compute the Time-Weighted Mean Absolute Error (TW-MAE).

This metric calculates the mean absolute error, giving different weights to errors at different time steps. It is useful when errors at certain points in a sequence (e.g., early predictions) are more or less important.

The formula for a single sequence i and output o is: .. math:

\mathrm{TWMAE}_{i,o} = \sum_{t=1}^{T}
w_t |\hat y_{i,o,t} - y_{i,o,t}|,

where \(T\) is the number of time steps (horizon length), \(w_t\) are the time weights (normalized to sum to 1), \(y_{i,o,t}\) is the true value, and \(\hat y_{i,o,t}\) is the predicted value for sample i, output o at time step t. The final score is an average over samples and possibly outputs.

Parameters:

y_true (array-like) – True target values. Expected shapes: - (n_samples, n_timesteps) for single output. - (n_samples, n_outputs, n_timesteps) for multi-output. The last dimension is always treated as the time dimension.
y_pred (array-like) – Predicted values, matching y_true in shape.
time_weights (array-like of shape (n_timesteps,), str, or None, default=``’inverse_time’``) –
Weights to apply to each time step. - If ‘inverse_time’, weights are \(w_t = 1/t\)

(1-indexed t), normalized to sum to 1.
- If an array-like is provided, it’s used directly and normalized to sum to 1. Its length must match n_timesteps.
- If None, uniform weights (1/T) are applied.
sample_weight (array-like of shape (n_samples,), optional) – Sample weights. If None, samples are equally weighted in the final aggregation.
nan_policy ({'omit', 'propagate', 'raise'}, default 'propagate') –
How to handle NaNs in y_true or y_pred:
- 'raise': Raise an error on any NaN.
- 'omit': Drop samples (rows) containing NaNs in either y_true or y_pred.
- 'propagate': The score for samples/outputs with NaNs will be NaN.
multioutput ({'raw_values', 'uniform_average'}, default 'uniform_average') –
Defines aggregation if y_true and y_pred have an n_outputs dimension.
- 'raw_values': Returns a score for each output.
- 'uniform_average': Scores of all outputs are averaged.
verbose (int, default 0) – Verbosity level: 0 (silent), 1 (summary), >=2 (debug details).

Returns:

score – Mean TW-MAE. Scalar if multioutput=’uniform_average’ or if inputs are 2D. Array of shape (n_outputs,) if multioutput=’raw_values’ and inputs are 3D.

Return type:

float or ndarray of floats

Examples

>>> import numpy as np
>>> # from fusionlab.metrics import time_weighted_mean_absolute_error

>>> # Single output (2 samples, 3 timesteps)
>>> y_t = np.array([[1, 2, 3], [2, 3, 4]])
>>> y_p = np.array([[1.1, 2.2, 2.9], [1.9, 3.1, 3.8]])
>>> # Default inverse_time weights for T=3:
>>> # w_raw = [1/1, 1/2, 1/3] = [1, 0.5, 0.333]
>>> # sum_w_raw = 1 + 0.5 + 0.333 = 1.833
>>> # w_norm = [1/1.833, 0.5/1.833, 0.333/1.833]
>>> #        = [0.545, 0.273, 0.182] (approx)
>>> score = time_weighted_mean_absolute_error(y_t, y_p)
>>> print(f"TW-MAE (default weights): {score:.4f}")
TW-MAE (default weights): 0.1303

>>> # Custom time weights
>>> custom_tw = np.array([0.5, 0.3, 0.2])
>>> score_custom = time_weighted_mean_absolute_error(
...     y_t, y_p, time_weights=custom_tw
... )
>>> print(f"TW-MAE (custom weights): {score_custom:.4f}")
TW-MAE (custom weights): 0.1200

>>> # Multi-output example
>>> y_t_mo = np.array([[[1,2],[10,20]], [[3,4],[30,40]]]) # (2s,2o,2t)
>>> y_p_mo = np.array([[[1,1],[11,19]], [[3,3],[31,39]]])
>>> score_mo = time_weighted_mean_absolute_error(
...     y_t_mo, y_p_mo, multioutput='raw_values',
...     time_weights=[0.6, 0.4]
... )
>>> print(f"TW-MAE (multi-output, raw): {score_mo}")
TW-MAE (multi-output, raw): [0.4 0.6]