MeanAsymmetricError

class MeanAsymmetricError(multioutput='uniform_average', multilevel='uniform_average', asymmetric_threshold=0, left_error_function='squared', right_error_function='absolute', left_error_penalty=1.0, right_error_penalty=1.0, by_index=False)[source]

Calculate mean of asymmetric loss function.

Output is non-negative floating point. The best value is 0.0.

Error values that are less than the asymmetric threshold have left_error_function applied. Error values greater than or equal to asymmetric threshold have right_error_function applied.

Many forecasting loss functions (like those discussed in [1]) assume that over- and under- predictions should receive an equal penalty. However, this may not align with the actual cost faced by users’ of the forecasts. Asymmetric loss functions are useful when the cost of under- and over- prediction are not the same.

Setting asymmetric_threshold to zero, left_error_function to ‘squared’ and right_error_function to ‘absolute` results in a greater penalty applied to over-predictions (y_true - y_pred < 0). The opposite is true for left_error_function set to ‘absolute’ and right_error_function set to ‘squared`.

The left_error_penalty and right_error_penalty can be used to add differing multiplicative penalties to over-predictions and under-predictions.

Parameters:

multioutput‘uniform_average’ (default), 1D array-like, or ‘raw_values’

Whether and how to aggregate metric for multivariate (multioutput) data.

If 'uniform_average' (default), errors of all outputs are averaged with uniform weight.
If 1D array-like, errors are averaged across variables, with values used as averaging weights (same order).
If 'raw_values', does not average across variables (outputs), per-variable errors are returned.

multilevel{‘raw_values’, ‘uniform_average’, ‘uniform_average_time’}

How to aggregate the metric for hierarchical data (with levels).

If 'uniform_average' (default), errors are mean-averaged across levels.
If 'uniform_average_time', metric is applied to all data, ignoring level index.
If 'raw_values', does not average errors across levels, hierarchy is retained.

asymmetric_thresholdfloat, default = 0.0

The value used to threshold the asymmetric loss function. Error values that are less than the asymmetric threshold have left_error_function applied. Error values greater than or equal to asymmetric threshold have right_error_function applied.

left_error_function{‘squared’, ‘absolute’}, default=’squared’

Loss penalty to apply to error values less than the asymmetric threshold.

right_error_function{‘squared’, ‘absolute’}, default=’absolute’

Loss penalty to apply to error values greater than or equal to the asymmetric threshold.

left_error_penaltyint or float, default=1.0

An additional multiplicative penalty to apply to error values less than the asymmetric threshold.

right_error_penaltyint or float, default=1.0

An additional multiplicative penalty to apply to error values greater than the asymmetric threshold.

by_indexbool, default=False

Controls averaging over time points in direct call to metric object.

If False (default), direct call to the metric object averages over time points, equivalent to a call of the evaluate method.
If True, direct call to the metric object evaluates the metric at each time point, equivalent to a call of the evaluate_by_index method.

Notes

Setting left_error_function and right_error_function to “absolute”, but choosing different values for left_error_penalty and right_error_penalty results in the “lin-lin” error function discussed in [2].

References

[1]

Hyndman, R. J and Koehler, A. B. (2006). “Another look at measures of forecast accuracy”, International Journal of Forecasting, Volume 22, Issue 4.

[2]

Diebold, Francis X. (2007). “Elements of Forecasting (4th ed.)”, Thomson, South-Western: Ohio, US.

Examples

>>> import numpy as np
>>> from sktime.performance_metrics.forecasting import MeanAsymmetricError
>>> y_true = np.array([3, -0.5, 2, 7, 2])
>>> y_pred = np.array([2.5, 0.0, 2, 8, 1.25])
>>> asymmetric_error = MeanAsymmetricError()
>>> asymmetric_error(y_true, y_pred)
np.float64(0.5)
>>> asymmetric_error = MeanAsymmetricError(left_error_function='absolute',     right_error_function='squared')
>>> asymmetric_error(y_true, y_pred)
np.float64(0.4625)
>>> y_true = np.array([[0.5, 1], [-1, 1], [7, -6]])
>>> y_pred = np.array([[0, 2], [-1, 2], [8, -5]])
>>> asymmetric_error = MeanAsymmetricError()
>>> asymmetric_error(y_true, y_pred)
np.float64(0.75)
>>> asymmetric_error = MeanAsymmetricError(left_error_function='absolute',     right_error_function='squared')
>>> asymmetric_error(y_true, y_pred)
np.float64(0.7083333333333334)
>>> asymmetric_error = MeanAsymmetricError(multioutput='raw_values')
>>> asymmetric_error(y_true, y_pred)
array([0.5, 1. ])
>>> asymmetric_error = MeanAsymmetricError(multioutput=[0.3, 0.7])
>>> asymmetric_error(y_true, y_pred)
np.float64(0.85)

Methods

__call__(y_true, y_pred, **kwargs)

Calculate metric value using underlying metric function.

__call__(y_true, y_pred, **kwargs)[source]

Calculate metric value using underlying metric function.

Parameters:

y_truetime series in sktime compatible data container format.

Ground truth (correct) target values.

Individual data formats in sktime are so-called mtype specifications, each mtype implements an abstract scitype.

Series scitype = individual time series, vanilla forecasting. pd.DataFrame, pd.Series, or np.ndarray (1D or 2D)
Panel scitype = collection of time series, global/panel forecasting. pd.DataFrame with 2-level row MultiIndex (instance, time), 3D np.ndarray (instance, variable, time), list of Series typed pd.DataFrame
Hierarchical scitype = hierarchical collection, for hierarchical forecasting. pd.DataFrame with 3 or more level row MultiIndex (hierarchy_1, ..., hierarchy_n, time)

For further details on data format, see glossary on mtype. For usage, see forecasting tutorial examples/01_forecasting.ipynb

y_predtime series in sktime compatible data container format

Predicted values to evaluate against ground truth. Must be of same format as y_true, same indices and columns if indexed.

y_pred_benchmarkoptional, time series in sktime compatible data container format

Benchmark predictions to compare y_pred to, used for relative metrics. Required only if metric requires benchmark predictions, as indicated by tag requires-y-pred-benchmark. Otherwise, can be passed to ensure interface consistency, but is ignored. Must be of same format as y_true, same indices and columns if indexed.

y_trainoptional, time series in sktime compatible data container format

Training data used to normalize the error metric. Required only if metric requires training data, as indicated by tag requires-y-train. Otherwise, can be passed to ensure interface consistency, but is ignored. Must be of same format as y_true, same columns if indexed, but not necessarily same indices.

sample_weightoptional, 1D array-like, or callable, default=None

Sample weights for each time point.

If None, the time indices are considered equally weighted.
If an array, must be 1D. If y_true and y_pred``are a single time series, ``sample_weight must be of the same length as y_true. If the time series are panel or hierarchical, the length of all individual time series must be the same, and equal to the length of sample_weight, for all instances of time series passed.
If a callable, it must follow SampleWeightGenerator interface, or have one of the following signatures: y_true: pd.DataFrame -> 1D array-like, or y_true: pd.DataFrame x y_pred: pd.DataFrame -> 1D array-like.

Returns:

lossfloat, np.ndarray, or pd.DataFrame

Calculated metric, averaged or by variable. Weighted by sample_weight if provided.

float if multioutput="uniform_average" or array-like, and ``multilevel="uniform_average" or “uniform_average_time”``. Value is metric averaged over variables and levels (see class docstring)
np.ndarray of shape (y_true.columns,) if multioutput=”raw_values”` and multilevel="uniform_average" or "uniform_average_time". i-th entry is the, metric calculated for i-th variable
pd.DataFrame if multilevel="raw_values". of shape (n_levels, ), if multioutput="uniform_average"; of shape (n_levels, y_true.columns) if multioutput="raw_values". metric is applied per level, row averaging (yes/no) as in multioutput.