autogluon.timeseries 1.0.1b20240304__py3-none-any.whl → 1.4.1b20251210__py3-none-any.whl

autogluon/timeseries/metrics/abstract.py

@@ -1,4 +1,5 @@
-from typing import Optional, Tuple
+import warnings
+from typing import Sequence, overload
 
 import numpy as np
 import pandas as pd
@@ -15,6 +16,18 @@ class TimeSeriesScorer:
 
     Follows the design of ``autogluon.core.metrics.Scorer``.
 
+    Parameters
+    ----------
+    prediction_length : int, default = 1
+        The length of the forecast horizon. The predictions provided to the ``TimeSeriesScorer`` are expected to contain
+        a forecast for this many time steps for each time series.
+    seasonal_period : int or None, default = None
+        Seasonal period used to compute some evaluation metrics such as mean absolute scaled error (MASE). Defaults to
+        ``None``, in which case the seasonal period is computed based on the data frequency.
+    horizon_weight : Sequence[float], np.ndarray or None, default = None
+        Weight assigned to each time step in the forecast horizon when computing the metric. If provided, the
+        ``horizon_weight`` will be stored as a numpy array of shape ``[1, prediction_length]``.
+
     Attributes
     ----------
     greater_is_better_internal : bool, default = False
@@ -30,15 +43,28 @@ class TimeSeriesScorer:
         Whether the given metric uses the quantile predictions. Some models will modify the training procedure if they
         are trained to optimize a quantile metric.
     equivalent_tabular_regression_metric : str
-        Name of an equivalent metric used by AutoGluon-Tabular with ``problem_type="regression"``. Used by models that
-        train a TabularPredictor under the hood. This attribute should only be specified by point forecast metrics.
+        Name of an equivalent metric used by AutoGluon-Tabular with ``problem_type="regression"``. Used by forecasting
+        models that train tabular regression models under the hood. This attribute should only be specified by point
+        forecast metrics.
     """
 
     greater_is_better_internal: bool = False
     optimum: float = 0.0
     optimized_by_median: bool = False
     needs_quantile: bool = False
-    equivalent_tabular_regression_metric: Optional[str] = None
+    equivalent_tabular_regression_metric: str | None = None
+
+    def __init__(
+        self,
+        prediction_length: int = 1,
+        seasonal_period: int | None = None,
+        horizon_weight: Sequence[float] | None = None,
+    ):
+        self.prediction_length = int(prediction_length)
+        if self.prediction_length < 1:
+            raise ValueError(f"prediction_length must be >= 1 (received {prediction_length})")
+        self.seasonal_period = seasonal_period
+        self.horizon_weight = self.check_get_horizon_weight(horizon_weight, prediction_length=prediction_length)
 
     @property
     def sign(self) -> int:
@@ -66,17 +92,25 @@ class TimeSeriesScorer:
         self,
         data: TimeSeriesDataFrame,
         predictions: TimeSeriesDataFrame,
-        prediction_length: int = 1,
         target: str = "target",
-        seasonal_period: Optional[int] = None,
         **kwargs,
     ) -> float:
-        seasonal_period = get_seasonality(data.freq) if seasonal_period is None else seasonal_period
-
-        data_past = data.slice_by_timestep(None, -prediction_length)
-        data_future = data.slice_by_timestep(-prediction_length, None)
-
-        assert (predictions.num_timesteps_per_item() == prediction_length).all()
+        seasonal_period = get_seasonality(data.freq) if self.seasonal_period is None else self.seasonal_period
+
+        if "prediction_length" in kwargs:
+            warnings.warn(
+                "Passing `prediction_length` to `TimeSeriesScorer.__call__` is deprecated and will be removed in v2.0. "
+                "Please set the `eval_metric.prediction_length` attribute instead.",
+                category=FutureWarning,
+            )
+            self.prediction_length = kwargs["prediction_length"]
+            self.horizon_weight = self.check_get_horizon_weight(self.horizon_weight, self.prediction_length)
+
+        data_past = data.slice_by_timestep(None, -self.prediction_length)
+        data_future = data.slice_by_timestep(-self.prediction_length, None)
+
+        assert not predictions.isna().any().any(), "Predictions contain NaN values."
+        assert (predictions.num_timesteps_per_item() == self.prediction_length).all()
         assert data_future.index.equals(predictions.index), "Prediction and data indices do not match."
 
         try:
@@ -114,10 +148,10 @@ class TimeSeriesScorer:
         ----------
         data_future : TimeSeriesDataFrame
             Actual values of the time series during the forecast horizon (``prediction_length`` values for each time
-            series in the dataset). This data frame is guaranteed to have the same index as ``predictions``.
+            series in the dataset). Must have the same index as ``predictions``.
         predictions : TimeSeriesDataFrame
             Data frame with predictions for the forecast horizon. Contain columns "mean" (point forecast) and the
-            columns corresponding to each of the quantile levels.
+            columns corresponding to each of the quantile levels. Must have the same index as ``data_future``.
         target : str, default = "target"
             Name of the column in ``data_future`` that contains the target time series.
 
@@ -139,7 +173,7 @@ class TimeSeriesScorer:
     ) -> None:
         """Compute auxiliary metrics on past data (before forecast horizon), if the chosen metric requires it.
 
-        This method should only be implemented by metrics that rely on historic (in-sample) data, such as Mean Absolute
+        This method should only be implemented by metrics that rely on historical (in-sample) data, such as Mean Absolute
         Scaled Error (MASE) https://en.wikipedia.org/wiki/Mean_absolute_scaled_error.
 
         We keep this method separate from :meth:`compute_metric` to avoid redundant computations when fitting ensemble.
@@ -158,21 +192,21 @@ class TimeSeriesScorer:
         return self.optimum - self.score(*args, **kwargs)
 
     @staticmethod
-    def _safemean(series: pd.Series) -> float:
-        """Compute mean of an pd.Series, ignoring inf, -inf and nan values."""
-        return np.nanmean(series.replace([np.inf, -np.inf], np.nan).values)
+    def _safemean(array: np.ndarray | pd.Series) -> float:
+        """Compute mean of a numpy array-like object, ignoring inf, -inf and nan values."""
+        return float(np.mean(array[np.isfinite(array)]))
 
     @staticmethod
     def _get_point_forecast_score_inputs(
         data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target"
-    ) -> Tuple[pd.Series, pd.Series]:
+    ) -> tuple[pd.Series, pd.Series]:
         """Get inputs necessary to compute point forecast metrics.
 
         Returns
         -------
-        y_true : pd.Series, shape [num_items * prediction_length]
+        y_true
             Target time series values during the forecast horizon.
-        y_pred : pd.Series, shape [num_items * prediction_length]
+        y_pred
             Predicted time series values during the forecast horizon.
         """
         y_true = data_future[target]
@@ -182,16 +216,16 @@ class TimeSeriesScorer:
     @staticmethod
     def _get_quantile_forecast_score_inputs(
         data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target"
-    ) -> Tuple[pd.Series, pd.DataFrame, np.ndarray]:
+    ) -> tuple[pd.Series, pd.DataFrame, np.ndarray]:
         """Get inputs necessary to compute quantile forecast metrics.
 
         Returns
         -------
-        y_true : pd.Series, shape [num_items * prediction_length]
+        y_true
             Target time series values during the forecast horizon.
-        q_pred : pd.DataFrame, shape [num_items * prediction_length, num_quantiles]
+        q_pred
             Quantile forecast for each predicted quantile level. Column order corresponds to ``quantile_levels``.
-        quantile_levels : np.ndarray, shape [num_quantiles]
+        quantile_levels
             Quantile levels for which the forecasts are generated (as floats).
         """
         quantile_columns = [col for col in predictions.columns if col != "mean"]
@@ -199,3 +233,40 @@ class TimeSeriesScorer:
         q_pred = pd.DataFrame(predictions[quantile_columns])
         quantile_levels = np.array(quantile_columns, dtype=float)
         return y_true, q_pred, quantile_levels
+
+    @overload
+    @staticmethod
+    def check_get_horizon_weight(horizon_weight: None, prediction_length: int) -> None: ...
+    @overload
+    @staticmethod
+    def check_get_horizon_weight(
+        horizon_weight: Sequence[float] | np.ndarray, prediction_length: int
+    ) -> np.ndarray: ...
+
+    @staticmethod
+    def check_get_horizon_weight(
+        horizon_weight: Sequence[float] | np.ndarray | None, prediction_length: int
+    ) -> np.ndarray | None:
+        """Convert horizon_weight to a non-negative numpy array that sums up to prediction_length.
+        Raises an exception if horizon_weight has an invalid shape or contains invalid values.
+
+        Returns
+        -------
+        horizon_weight
+            None if the input is None, otherwise a numpy array of shape [1, prediction_length].
+        """
+        if horizon_weight is None:
+            return None
+        horizon_weight_np = np.ravel(horizon_weight).astype(np.float64)
+        if horizon_weight_np.shape != (prediction_length,):
+            raise ValueError(
+                f"horizon_weight must have length equal to {prediction_length=} (got {len(horizon_weight)=})"
+            )
+        if not (horizon_weight_np >= 0).all():
+            raise ValueError(f"All values in horizon_weight must be >= 0 (got {horizon_weight})")
+        if not horizon_weight_np.sum() > 0:
+            raise ValueError(f"At least some values in horizon_weight must be > 0 (got {horizon_weight})")
+        if not np.isfinite(horizon_weight_np).all():
+            raise ValueError(f"All horizon_weight values must be finite (got {horizon_weight})")
+        horizon_weight_np = horizon_weight_np * prediction_length / horizon_weight_np.sum()
+        return horizon_weight_np.reshape([1, prediction_length])

autogluon/timeseries/metrics/point.py

@@ -1,14 +1,14 @@
 import logging
-from typing import Optional
+import warnings
+from typing import Sequence
 
 import numpy as np
 import pandas as pd
 
 from autogluon.timeseries import TimeSeriesDataFrame
-from autogluon.timeseries.dataset.ts_dataframe import ITEMID
 
 from .abstract import TimeSeriesScorer
-from .utils import _in_sample_abs_seasonal_error, _in_sample_squared_seasonal_error
+from .utils import in_sample_abs_seasonal_error, in_sample_squared_seasonal_error
 
 logger = logging.getLogger(__name__)
 
@@ -38,10 +38,18 @@ class RMSE(TimeSeriesScorer):
     equivalent_tabular_regression_metric = "root_mean_squared_error"
 
     def compute_metric(
-        self, data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target", **kwargs
+        self,
+        data_future: TimeSeriesDataFrame,
+        predictions: TimeSeriesDataFrame,
+        target: str = "target",
+        **kwargs,
     ) -> float:
         y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
-        return np.sqrt(self._safemean((y_true - y_pred) ** 2))
+        y_true, y_pred = y_true.to_numpy(), y_pred.to_numpy()
+        errors = ((y_true - y_pred) ** 2).reshape([-1, self.prediction_length])
+        if self.horizon_weight is not None:
+            errors *= self.horizon_weight
+        return np.sqrt(self._safemean(errors))
 
 
 class MSE(TimeSeriesScorer):
@@ -69,10 +77,18 @@ class MSE(TimeSeriesScorer):
     equivalent_tabular_regression_metric = "mean_squared_error"
 
     def compute_metric(
-        self, data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target", **kwargs
+        self,
+        data_future: TimeSeriesDataFrame,
+        predictions: TimeSeriesDataFrame,
+        target: str = "target",
+        **kwargs,
     ) -> float:
         y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
-        return self._safemean((y_true - y_pred) ** 2)
+        y_true, y_pred = y_true.to_numpy(), y_pred.to_numpy()
+        errors = ((y_true - y_pred) ** 2).reshape([-1, self.prediction_length])
+        if self.horizon_weight is not None:
+            errors *= self.horizon_weight
+        return self._safemean(errors)
 
 
 class MAE(TimeSeriesScorer):
@@ -98,10 +114,18 @@ class MAE(TimeSeriesScorer):
     equivalent_tabular_regression_metric = "mean_absolute_error"
 
     def compute_metric(
-        self, data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target", **kwargs
+        self,
+        data_future: TimeSeriesDataFrame,
+        predictions: TimeSeriesDataFrame,
+        target: str = "target",
+        **kwargs,
     ) -> float:
         y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
-        return self._safemean((y_true - y_pred).abs())
+        y_true, y_pred = y_true.to_numpy(), y_pred.to_numpy()
+        errors = np.abs(y_true - y_pred).reshape([-1, self.prediction_length])
+        if self.horizon_weight is not None:
+            errors *= self.horizon_weight
+        return self._safemean(errors)
 
 
 class WAPE(TimeSeriesScorer):
@@ -119,6 +143,7 @@ class WAPE(TimeSeriesScorer):
     - not sensitive to outliers
     - prefers models that accurately estimate the median
 
+    If ``self.horizon_weight`` is provided, both the errors and the target time series in the denominator will be re-weighted.
 
     References
     ----------
@@ -129,10 +154,19 @@ class WAPE(TimeSeriesScorer):
     equivalent_tabular_regression_metric = "mean_absolute_error"
 
     def compute_metric(
-        self, data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target", **kwargs
+        self,
+        data_future: TimeSeriesDataFrame,
+        predictions: TimeSeriesDataFrame,
+        target: str = "target",
+        **kwargs,
     ) -> float:
         y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
-        return (y_true - y_pred).abs().sum() / y_true.abs().sum()
+        y_true, y_pred = y_true.to_numpy(), y_pred.to_numpy()
+        errors = np.abs(y_true - y_pred).reshape([-1, self.prediction_length])
+        if self.horizon_weight is not None:
+            errors *= self.horizon_weight
+            y_true = y_true.reshape([-1, self.prediction_length]) * self.horizon_weight
+        return np.nansum(errors) / np.nansum(np.abs(y_true))
 
 
 class SMAPE(TimeSeriesScorer):
@@ -158,10 +192,18 @@ class SMAPE(TimeSeriesScorer):
     equivalent_tabular_regression_metric = "symmetric_mean_absolute_percentage_error"
 
     def compute_metric(
-        self, data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target", **kwargs
+        self,
+        data_future: TimeSeriesDataFrame,
+        predictions: TimeSeriesDataFrame,
+        target: str = "target",
+        **kwargs,
     ) -> float:
         y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
-        return self._safemean(2 * ((y_true - y_pred).abs() / (y_true.abs() + y_pred.abs())))
+        y_true, y_pred = y_true.to_numpy(), y_pred.to_numpy()
+        errors = (np.abs(y_true - y_pred) / (np.abs(y_true) + np.abs(y_pred))).reshape([-1, self.prediction_length])
+        if self.horizon_weight is not None:
+            errors *= self.horizon_weight
+        return 2 * self._safemean(errors)
 
 
 class MAPE(TimeSeriesScorer):
@@ -187,22 +229,30 @@ class MAPE(TimeSeriesScorer):
     equivalent_tabular_regression_metric = "mean_absolute_percentage_error"
 
     def compute_metric(
-        self, data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target", **kwargs
+        self,
+        data_future: TimeSeriesDataFrame,
+        predictions: TimeSeriesDataFrame,
+        target: str = "target",
+        **kwargs,
     ) -> float:
         y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
-        return self._safemean((y_true - y_pred).abs() / y_true.abs())
+        y_true, y_pred = y_true.to_numpy(), y_pred.to_numpy()
+        errors = (np.abs(y_true - y_pred) / np.abs(y_true)).reshape([-1, self.prediction_length])
+        if self.horizon_weight is not None:
+            errors *= self.horizon_weight
+        return self._safemean(errors)
 
 
 class MASE(TimeSeriesScorer):
     r"""Mean absolute scaled error.
 
-    Normalizes the absolute error for each time series by the historic seasonal error of this time series.
+    Normalizes the absolute error for each time series by the historical seasonal error of this time series.
 
     .. math::
 
         \operatorname{MASE} = \frac{1}{N} \frac{1}{H} \sum_{i=1}^{N} \frac{1}{a_i} \sum_{t=T+1}^{T+H} |y_{i,t} - f_{i,t}|
 
-    where :math:`a_i` is the historic absolute seasonal error defined as
+    where :math:`a_i` is the historical absolute seasonal error defined as
 
     .. math::
 
@@ -226,13 +276,21 @@ class MASE(TimeSeriesScorer):
     optimized_by_median = True
     equivalent_tabular_regression_metric = "mean_absolute_error"
 
-    def __init__(self):
-        self._past_abs_seasonal_error: Optional[pd.Series] = None
+    def __init__(
+        self,
+        prediction_length: int = 1,
+        seasonal_period: int | None = None,
+        horizon_weight: Sequence[float] | None = None,
+    ):
+        super().__init__(
+            prediction_length=prediction_length, seasonal_period=seasonal_period, horizon_weight=horizon_weight
+        )
+        self._past_abs_seasonal_error: pd.Series | None = None
 
     def save_past_metrics(
         self, data_past: TimeSeriesDataFrame, target: str = "target", seasonal_period: int = 1, **kwargs
     ) -> None:
-        self._past_abs_seasonal_error = _in_sample_abs_seasonal_error(
+        self._past_abs_seasonal_error = in_sample_abs_seasonal_error(
             y_past=data_past[target], seasonal_period=seasonal_period
         )
 
@@ -240,26 +298,34 @@ class MASE(TimeSeriesScorer):
         self._past_abs_seasonal_error = None
 
     def compute_metric(
-        self, data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target", **kwargs
+        self,
+        data_future: TimeSeriesDataFrame,
+        predictions: TimeSeriesDataFrame,
+        target: str = "target",
+        **kwargs,
     ) -> float:
-        y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
         if self._past_abs_seasonal_error is None:
             raise AssertionError("Call `save_past_metrics` before `compute_metric`")
 
-        mae_per_item = (y_true - y_pred).abs().groupby(level=ITEMID, sort=False).mean()
-        return self._safemean(mae_per_item / self._past_abs_seasonal_error)
+        y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
+        y_true, y_pred = y_true.to_numpy(), y_pred.to_numpy()
+
+        errors = np.abs(y_true - y_pred).reshape([-1, self.prediction_length])
+        if self.horizon_weight is not None:
+            errors *= self.horizon_weight
+        return self._safemean(errors / self._past_abs_seasonal_error.to_numpy()[:, None])
 
 
 class RMSSE(TimeSeriesScorer):
     r"""Root mean squared scaled error.
 
-    Normalizes the absolute error for each time series by the historic seasonal error of this time series.
+    Normalizes the absolute error for each time series by the historical seasonal error of this time series.
 
     .. math::
 
         \operatorname{RMSSE} = \sqrt{\frac{1}{N} \frac{1}{H} \sum_{i=1}^{N} \frac{1}{s_i} \sum_{t=T+1}^{T+H} (y_{i,t} - f_{i,t})^2}
 
-    where :math:`s_i` is the historic squared seasonal error defined as
+    where :math:`s_i` is the historical squared seasonal error defined as
 
     .. math::
 
@@ -284,13 +350,21 @@ class RMSSE(TimeSeriesScorer):
 
     equivalent_tabular_regression_metric = "root_mean_squared_error"
 
-    def __init__(self):
-        self._past_squared_seasonal_error: Optional[pd.Series] = None
+    def __init__(
+        self,
+        prediction_length: int = 1,
+        seasonal_period: int | None = None,
+        horizon_weight: Sequence[float] | None = None,
+    ):
+        super().__init__(
+            prediction_length=prediction_length, seasonal_period=seasonal_period, horizon_weight=horizon_weight
+        )
+        self._past_squared_seasonal_error: pd.Series | None = None
 
     def save_past_metrics(
         self, data_past: TimeSeriesDataFrame, target: str = "target", seasonal_period: int = 1, **kwargs
     ) -> None:
-        self._past_squared_seasonal_error = _in_sample_squared_seasonal_error(
+        self._past_squared_seasonal_error = in_sample_squared_seasonal_error(
             y_past=data_past[target], seasonal_period=seasonal_period
         )
 
@@ -298,14 +372,21 @@ class RMSSE(TimeSeriesScorer):
         self._past_squared_seasonal_error = None
 
     def compute_metric(
-        self, data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target", **kwargs
+        self,
+        data_future: TimeSeriesDataFrame,
+        predictions: TimeSeriesDataFrame,
+        target: str = "target",
+        **kwargs,
     ) -> float:
-        y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
         if self._past_squared_seasonal_error is None:
             raise AssertionError("Call `save_past_metrics` before `compute_metric`")
 
-        mse_per_item = (y_true - y_pred).pow(2.0).groupby(level=ITEMID, sort=False).mean()
-        return np.sqrt(self._safemean(mse_per_item / self._past_squared_seasonal_error))
+        y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
+        y_true, y_pred = y_true.to_numpy(), y_pred.to_numpy()
+        errors = ((y_true - y_pred) ** 2).reshape([-1, self.prediction_length])
+        if self.horizon_weight is not None:
+            errors *= self.horizon_weight
+        return np.sqrt(self._safemean(errors / self._past_squared_seasonal_error.to_numpy()[:, None]))
 
 
 class RMSLE(TimeSeriesScorer):
@@ -331,19 +412,27 @@ class RMSLE(TimeSeriesScorer):
     - `Scikit-learn: <https://scikit-learn.org/stable/modules/model_evaluation.html#mean-squared-log-error>`_
     """
 
-    def compute_metric(self, data_future, predictions, target, **kwargs):
+    def compute_metric(
+        self,
+        data_future: TimeSeriesDataFrame,
+        predictions: TimeSeriesDataFrame,
+        target: str = "target",
+        **kwargs,
+    ) -> float:
         y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
+        y_true, y_pred = y_true.to_numpy(), y_pred.to_numpy()
         y_pred = np.clip(y_pred, a_min=0.0, a_max=None)
 
-        return np.sqrt(np.power(np.log1p(y_pred) - np.log1p(y_true), 2).mean())
+        errors = np.power(np.log1p(y_pred) - np.log1p(y_true), 2).reshape([-1, self.prediction_length])
+        if self.horizon_weight is not None:
+            errors *= self.horizon_weight
+        return np.sqrt(self._safemean(errors))
 
     def __call__(
         self,
         data: TimeSeriesDataFrame,
         predictions: TimeSeriesDataFrame,
-        prediction_length: int = 1,
         target: str = "target",
-        seasonal_period: Optional[int] = None,
         **kwargs,
     ) -> float:
         if (data[target] < 0).any():
@@ -351,8 +440,66 @@ class RMSLE(TimeSeriesScorer):
         return super().__call__(
             data=data,
             predictions=predictions,
-            prediction_length=prediction_length,
             target=target,
-            seasonal_period=seasonal_period,
             **kwargs,
         )
+
+
+class WCD(TimeSeriesScorer):
+    r"""Weighted cumulative discrepancy.
+
+    Measures the discrepancy between the cumulative sum of the forecast and the cumulative sum of the actual values.
+
+    .. math::
+
+        \operatorname{WCD} = 2 \cdot \frac{1}{N} \frac{1}{H} \sum_{i=1}^{N} \sum_{t=T+1}^{T+H} \alpha \cdot \max(0, -d_{i, t}) + (1 - \alpha) \cdot \max(0, d_{i, t})
+
+    where :math:`d_{i, t}` is the difference between the cumulative predicted value and the cumulative actual value
+
+    .. math::
+
+        d_{i, t} = \left(\sum_{s=T+1}^t f_{i, s}) - \left(\sum_{s=T+1}^t y_{i, s})
+
+    Parameters
+    ----------
+    alpha : float, default = 0.5
+        Values > 0.5 put a stronger penalty on underpredictions (when cumulative forecast is below the
+        cumulative actual value). Values < 0.5 put a stronger penalty on overpredictions.
+    """
+
+    def __init__(
+        self,
+        alpha: float = 0.5,
+        prediction_length: int = 1,
+        seasonal_period: int | None = None,
+        horizon_weight: Sequence[float] | None = None,
+    ):
+        super().__init__(
+            prediction_length=prediction_length, seasonal_period=seasonal_period, horizon_weight=horizon_weight
+        )
+        assert 0 < alpha < 1, "alpha must be in (0, 1)"
+        self.alpha = alpha
+        warnings.warn(
+            f"{self.name} is an experimental metric. Its behavior may change in the future version of AutoGluon."
+        )
+
+    def _fast_cumsum(self, y: np.ndarray) -> np.ndarray:
+        """Compute the cumulative sum for each consecutive `self.prediction_length` items in the array."""
+        y = y.reshape(-1, self.prediction_length)
+        return np.nancumsum(y, axis=1).ravel()
+
+    def compute_metric(
+        self,
+        data_future: TimeSeriesDataFrame,
+        predictions: TimeSeriesDataFrame,
+        target: str = "target",
+        **kwargs,
+    ) -> float:
+        y_true, y_pred = self._get_point_forecast_score_inputs(data_future, predictions, target=target)
+        cumsum_true = self._fast_cumsum(y_true.to_numpy())
+        cumsum_pred = self._fast_cumsum(y_pred.to_numpy())
+        diffs = cumsum_pred - cumsum_true
+        errors = (diffs * np.where(diffs < 0, -self.alpha, (1 - self.alpha))).reshape([-1, self.prediction_length])
+        if self.horizon_weight is not None:
+            errors *= self.horizon_weight
+        return 2 * self._safemean(errors)