autogluon.timeseries 1.1.2b20240925__py3-none-any.whl → 1.1.2b20240926__py3-none-any.whl

autogluon/timeseries/models/abstract/abstract_timeseries_model.py

@@ -13,6 +13,7 @@ from autogluon.core.hpo.executors import HpoExecutor, RayHpoExecutor
 from autogluon.core.models import AbstractModel
 from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.metrics import TimeSeriesScorer, check_get_evaluation_metric
+from autogluon.timeseries.transforms import LocalTargetScaler, get_target_scaler_from_name
 from autogluon.timeseries.utils.features import CovariateMetadata
 from autogluon.timeseries.utils.warning_filters import disable_stdout, warning_filter
 
@@ -122,6 +123,7 @@ class AbstractTimeSeriesModel(AbstractModel):
             self.must_drop_median = False
 
         self._oof_predictions: Optional[List[TimeSeriesDataFrame]] = None
+        self.target_scaler: Optional[LocalTargetScaler] = None
 
     def __repr__(self) -> str:
         return self.name
@@ -241,11 +243,32 @@ class AbstractTimeSeriesModel(AbstractModel):
         model: AbstractTimeSeriesModel
             The fitted model object
         """
+        self.initialize(**kwargs)
+        self.target_scaler = self._create_target_scaler()
+        if self.target_scaler is not None:
+            train_data = self.target_scaler.fit_transform(train_data)
+
         train_data = self.preprocess(train_data, is_train=True)
         if self._get_tags()["can_use_val_data"] and val_data is not None:
+            if self.target_scaler is not None:
+                val_data = self.target_scaler.transform(val_data)
             val_data = self.preprocess(val_data, is_train=False)
         return super().fit(train_data=train_data, val_data=val_data, **kwargs)
 
+    @property
+    def allowed_hyperparameters(self) -> List[str]:
+        """List of hyperparameters allowed by the model."""
+        return ["target_scaler"]
+
+    def _create_target_scaler(self) -> Optional[LocalTargetScaler]:
+        """Create a LocalTargetScaler object based on the value of the `target_scaler` hyperparameter."""
+        # TODO: Add support for custom target transforms (e.g., Box-Cox, log1p, ...)
+        target_scaler_type = self._get_model_params().get("target_scaler")
+        if target_scaler_type is not None:
+            return get_target_scaler_from_name(target_scaler_type, target=self.target)
+        else:
+            return None
+
     def _fit(
         self,
         train_data: TimeSeriesDataFrame,
@@ -299,6 +322,9 @@ class AbstractTimeSeriesModel(AbstractModel):
             data is given as a separate forecast item in the dictionary, keyed by the `item_id`s
             of input items.
         """
+        if self.target_scaler is not None:
+            data = self.target_scaler.fit_transform(data)
+
         data = self.preprocess(data, is_train=False)
         known_covariates = self.preprocess_known_covariates(known_covariates)
         predictions = self._predict(data=data, known_covariates=known_covariates, **kwargs)
@@ -309,6 +335,9 @@ class AbstractTimeSeriesModel(AbstractModel):
                 predictions["mean"] = predictions["0.5"]
             if self.must_drop_median:
                 predictions = predictions.drop("0.5", axis=1)
+
+        if self.target_scaler is not None:
+            predictions = self.target_scaler.inverse_transform(predictions)
         return predictions
 
     def _predict(

autogluon/timeseries/models/autogluon_tabular/mlforecast.py

@@ -21,11 +21,9 @@ from autogluon.timeseries.utils.datetime import (
 from autogluon.timeseries.utils.forecast import get_forecast_horizon_index_ts_dataframe
 from autogluon.timeseries.utils.warning_filters import warning_filter
 
-logger = logging.getLogger(__name__)
+from .utils import MLF_ITEMID, MLF_TARGET, MLF_TIMESTAMP
 
-MLF_TARGET = "y"
-MLF_ITEMID = "unique_id"
-MLF_TIMESTAMP = "ds"
+logger = logging.getLogger(__name__)
 
 
 class TabularEstimator(BaseEstimator):
@@ -137,7 +135,7 @@ class AbstractMLForecastModel(AbstractTimeSeriesModel):
     def _get_mlforecast_init_args(self, train_data: TimeSeriesDataFrame, model_params: dict) -> dict:
         from mlforecast.target_transforms import Differences
 
-        from .utils import MeanAbsScaler, StandardScaler
+        from .transforms import MLForecastScaler
 
         lags = model_params.get("lags")
         if lags is None:
@@ -167,19 +165,10 @@ class AbstractMLForecastModel(AbstractTimeSeriesModel):
             target_transforms.append(Differences(differences))
             self._sum_of_differences = sum(differences)
 
-        scaler_name = model_params.get("scaler")
-        if scaler_name is None:
-            pass
-        elif scaler_name == "standard":
-            self._scaler = StandardScaler()
-        elif scaler_name == "mean_abs":
-            self._scaler = MeanAbsScaler()
-        else:
-            logger.warning(
-                f"Unrecognized `scaler` {scaler_name} (supported options: ['standard', 'mean_abs', None]). Scaling disabled."
-            )
-
-        if self._scaler is not None:
+        # Support "scaler" for backward compatibility
+        scaler_type = model_params.get("target_scaler", model_params.get("scaler"))
+        if scaler_type is not None:
+            self._scaler = MLForecastScaler(scaler_type=scaler_type)
             target_transforms.append(self._scaler)
 
         return {
@@ -323,7 +312,7 @@ class AbstractMLForecastModel(AbstractTimeSeriesModel):
             },
             predictor_fit_kwargs={
                 "tuning_data": val_df.drop(columns=[MLF_ITEMID]),
-                "time_limit": None if time_limit is None else time_limit - (time.time() - fit_start_time),
+                "time_limit": (None if time_limit is None else time_limit - (time.time() - fit_start_time)),
                 "hyperparameters": model_params["tabular_hyperparameters"],
                 **model_params["tabular_fit_kwargs"],
             },
@@ -340,14 +329,18 @@ class AbstractMLForecastModel(AbstractTimeSeriesModel):
 
         Saves per-item residuals to `self.residuals_std_per_item` and average std to `self._avg_residuals_std`.
         """
-        residuals = val_df[MLF_TARGET] - self._mlf.models_["mean"].predict(val_df)
-        self._residuals_std_per_item = residuals.pow(2.0).groupby(val_df[MLF_ITEMID], sort=False).mean().pow(0.5)
+        residuals_df = val_df[[MLF_ITEMID, MLF_TARGET]]
+        residuals_df = residuals_df.assign(y_pred=self._mlf.models_["mean"].predict(val_df))
+        if self._scaler is not None:
+            # Scaler expects to find column MLF_TIMESTAMP even though it's not used - fill with dummy
+            residuals_df = residuals_df.assign(**{MLF_TIMESTAMP: 1})
+            residuals_df = self._scaler.inverse_transform(residuals_df)
+        residuals = residuals_df[MLF_TARGET] - residuals_df["y_pred"]
+        self._residuals_std_per_item = (
+            residuals.pow(2.0).groupby(val_df[MLF_ITEMID].values, sort=False).mean().pow(0.5)
+        )
         self._avg_residuals_std = np.sqrt(residuals.pow(2.0).mean())
 
-    def _get_scale_per_item(self, item_ids: pd.Index) -> pd.Series:
-        """Extract the '_scale' values from the scaler object, if available."""
-        raise NotImplementedError
-
     def _remove_short_ts_and_generate_fallback_forecast(
         self,
         data: TimeSeriesDataFrame,
@@ -399,7 +392,6 @@ class AbstractMLForecastModel(AbstractTimeSeriesModel):
         """
         from scipy.stats import norm
 
-        scale_per_item = self._get_scale_per_item(repeated_item_ids.unique())
         num_items = int(len(predictions) / self.prediction_length)
         sqrt_h = np.sqrt(np.arange(1, self.prediction_length + 1))
         # Series where normal_scale_per_timestep.loc[item_id].loc[N] = sqrt(1 + N) for N in range(prediction_length)
@@ -409,7 +401,7 @@ class AbstractMLForecastModel(AbstractTimeSeriesModel):
         # Use avg_residuals_std in case unseen item received for prediction
         if residuals_std_per_timestep.isna().any():
             residuals_std_per_timestep = residuals_std_per_timestep.fillna(value=self._avg_residuals_std)
-        std_per_timestep = residuals_std_per_timestep * scale_per_item * normal_scale_per_timestep
+        std_per_timestep = residuals_std_per_timestep * normal_scale_per_timestep
         for q in self.quantile_levels:
             predictions[str(q)] = predictions["mean"] + norm.ppf(q) * std_per_timestep.to_numpy()
         return predictions
@@ -417,6 +409,10 @@ class AbstractMLForecastModel(AbstractTimeSeriesModel):
     def _more_tags(self) -> dict:
         return {"allow_nan": True, "can_refit_full": True}
 
+    def _create_target_scaler(self):
+        # Do not create a scaler in the model, scaler will be passed to MLForecast
+        return None
+
 
 class DirectTabularModel(AbstractMLForecastModel):
     """Predict all future time series values simultaneously using TabularPredictor from AutoGluon-Tabular.
@@ -449,8 +445,8 @@ class DirectTabularModel(AbstractMLForecastModel):
         Differences to take of the target before computing the features. These are restored at the forecasting step.
         If None, will be set to ``[seasonal_period]``, where seasonal_period is determined based on the data frequency.
         Defaults to no differencing.
-    scaler : {"standard", "mean_abs", None}, default = "mean_abs"
-        Scaling applied to each time series.
+    target_scaler : {"standard", "mean_abs", "min_max", "robust", None}, default = "mean_abs"
+        Scaling applied to each time series. Scaling is applied after differencing.
     tabular_hyperparameters : Dict[Dict[str, Any]], optional
         Hyperparameters dictionary passed to ``TabularPredictor.fit``. Contains the names of models that should be fit.
         Defaults to ``{"GBM": {}}``.
@@ -472,8 +468,9 @@ class DirectTabularModel(AbstractMLForecastModel):
 
     def _get_model_params(self) -> dict:
         model_params = super()._get_model_params()
-        model_params.setdefault("scaler", "mean_abs")
-        model_params.setdefault("differences", [])
+        model_params.setdefault("target_scaler", "mean_abs")
+        if "differences" not in model_params or model_params["differences"] is None:
+            model_params["differences"] = []
         return model_params
 
     def _mask_df(self, df: pd.DataFrame) -> pd.DataFrame:
@@ -501,6 +498,8 @@ class DirectTabularModel(AbstractMLForecastModel):
         known_covariates: Optional[TimeSeriesDataFrame] = None,
         **kwargs,
     ) -> TimeSeriesDataFrame:
+        from .transforms import apply_inverse_transform
+
         original_item_id_order = data.item_ids
         data, known_covariates, forecast_for_short_series = self._remove_short_ts_and_generate_fallback_forecast(
             data=data, known_covariates=known_covariates
@@ -536,9 +535,12 @@ class DirectTabularModel(AbstractMLForecastModel):
             mlforecast_df_past = self._to_mlforecast_df(data, None)
             if self._max_ts_length is not None:
                 mlforecast_df_past = self._shorten_all_series(mlforecast_df_past, self._max_ts_length)
-            self._mlf.preprocess(mlforecast_df_past, static_features=[])
+            self._mlf.preprocess(mlforecast_df_past, static_features=[], dropna=False)
             for tfm in self._mlf.ts.target_transforms[::-1]:
-                predictions = tfm.inverse_transform(predictions)
+                predictions = apply_inverse_transform(predictions, transform=tfm)
+
+        if not self.is_quantile_model:
+            predictions = self._add_gaussian_quantiles(predictions, repeated_item_ids=predictions[MLF_ITEMID])
         predictions = TimeSeriesDataFrame(predictions.rename(columns={MLF_ITEMID: ITEMID, MLF_TIMESTAMP: TIMESTAMP}))
 
         if forecast_for_short_series is not None:
@@ -553,15 +555,10 @@ class DirectTabularModel(AbstractMLForecastModel):
             predictions["mean"] = predictions["0.5"]
         else:
             predictions = pd.DataFrame(predictions, columns=["mean"])
-            predictions = self._add_gaussian_quantiles(predictions, repeated_item_ids=repeated_item_ids)
 
         column_order = ["mean"] + [col for col in predictions.columns if col != "mean"]
         return predictions[column_order]
 
-    def _get_scale_per_item(self, item_ids: pd.Index) -> pd.Series:
-        # Rescaling is applied in the inverse_transform step, no need to scale predictions
-        return pd.Series(1.0, index=item_ids)
-
     def _get_extra_tabular_init_kwargs(self) -> dict:
         if self.is_quantile_model:
             return {
@@ -603,8 +600,8 @@ class RecursiveTabularModel(AbstractMLForecastModel):
     differences : List[int], default = None
         Differences to take of the target before computing the features. These are restored at the forecasting step.
         If None, will be set to ``[seasonal_period]``, where seasonal_period is determined based on the data frequency.
-    scaler : {"standard", "mean_abs", None}, default = "standard"
-        Scaling applied to each time series.
+    target_scaler : {"standard", "mean_abs", "min_max", "robust", None}, default = "standard"
+        Scaling applied to each time series. Scaling is applied after differencing.
     tabular_hyperparameters : Dict[Dict[str, Any]], optional
         Hyperparameters dictionary passed to ``TabularPredictor.fit``. Contains the names of models that should be fit.
         Defaults to ``{"GBM": {}}``.
@@ -622,8 +619,9 @@ class RecursiveTabularModel(AbstractMLForecastModel):
 
     def _get_model_params(self) -> dict:
         model_params = super()._get_model_params()
-        model_params.setdefault("scaler", "standard")
-        model_params.setdefault("differences", [get_seasonality(self.freq)])
+        model_params.setdefault("target_scaler", "standard")
+        if "differences" not in model_params or model_params["differences"] is None:
+            model_params["differences"] = [get_seasonality(self.freq)]
         return model_params
 
     def _predict(
@@ -670,9 +668,3 @@ class RecursiveTabularModel(AbstractMLForecastModel):
             "problem_type": ag.constants.REGRESSION,
             "eval_metric": self.eval_metric.equivalent_tabular_regression_metric or "mean_absolute_error",
         }
-
-    def _get_scale_per_item(self, item_ids: pd.Index) -> pd.Series:
-        if self._scaler is not None:
-            return self._scaler.stats_["_scale"].copy().reindex(item_ids)
-        else:
-            return pd.Series(1.0, index=item_ids)

autogluon/timeseries/models/autogluon_tabular/transforms.py

@@ -0,0 +1,60 @@
+from typing import Literal, Optional, Union
+
+import numpy as np
+import pandas as pd
+from mlforecast.target_transforms import (
+    BaseTargetTransform,
+    GroupedArray,
+    _BaseGroupedArrayTargetTransform,
+)
+
+from autogluon.timeseries.dataset.ts_dataframe import (
+    ITEMID,
+    TIMESTAMP,
+    TimeSeriesDataFrame,
+)
+from autogluon.timeseries.transforms.scaler import LocalTargetScaler, get_target_scaler_from_name
+
+from .utils import MLF_ITEMID, MLF_TIMESTAMP
+
+
+class MLForecastScaler(BaseTargetTransform):
+    def __init__(self, scaler_type: Literal["standard", "robust", "min_max", "mean_abs"]):
+        # For backward compatibility
+        self.scaler_type = scaler_type
+        self.ag_scaler: Optional[LocalTargetScaler] = None
+
+    def _df_to_tsdf(self, df: pd.DataFrame) -> TimeSeriesDataFrame:
+        return df.rename(columns={self.id_col: ITEMID, self.time_col: TIMESTAMP}).set_index([ITEMID, TIMESTAMP])
+
+    def _tsdf_to_df(self, ts_df: TimeSeriesDataFrame) -> pd.DataFrame:
+        return pd.DataFrame(ts_df).reset_index().rename(columns={ITEMID: self.id_col, TIMESTAMP: self.time_col})
+
+    def fit_transform(self, df: pd.DataFrame) -> pd.DataFrame:
+        self.ag_scaler = get_target_scaler_from_name(name=self.scaler_type, target=self.target_col)
+        transformed = self.ag_scaler.fit_transform(self._df_to_tsdf(df)).reset_index()
+        return self._tsdf_to_df(transformed)
+
+    def inverse_transform(self, df: pd.DataFrame) -> pd.DataFrame:
+        transformed = self.ag_scaler.inverse_transform(self._df_to_tsdf(df))
+        return self._tsdf_to_df(transformed)
+
+
+def apply_inverse_transform(
+    df: pd.DataFrame,
+    transform: Union[_BaseGroupedArrayTargetTransform, BaseTargetTransform],
+) -> pd.DataFrame:
+    """Apply inverse transformation to a dataframe, converting to GroupedArray if necessary"""
+    if isinstance(transform, BaseTargetTransform):
+        return transform.inverse_transform(df=df)
+    elif isinstance(transform, _BaseGroupedArrayTargetTransform):
+        indptr = np.concatenate([[0], df[MLF_ITEMID].value_counts().cumsum()])
+        assignment = {}
+        for col in df.columns.drop([MLF_ITEMID, MLF_TIMESTAMP]):
+            ga = GroupedArray(data=df[col].to_numpy(), indptr=indptr)
+            assignment[col] = transform.inverse_transform(ga).data
+        return df.assign(**assignment)
+    else:
+        raise ValueError(
+            f"transform must be of type `_BaseGroupedArrayTargetTransform` or `BaseTargetTransform` (got {type(transform)})"
+        )

autogluon/timeseries/models/autogluon_tabular/utils.py

@@ -1,51 +1,3 @@
-import numpy as np
-import pandas as pd
-from mlforecast.target_transforms import BaseTargetTransform
-
-
-class StandardScaler(BaseTargetTransform):
-    """Standardizes the series by subtracting mean and diving by standard deviation."""
-
-    min_scale: float = 1e-2
-
-    def fit_transform(self, df: pd.DataFrame) -> pd.DataFrame:
-        self.stats_ = (
-            df.replace([np.inf, -np.inf], np.nan)
-            .groupby(self.id_col)[self.target_col]
-            .agg(["mean", "std"])
-            .rename(columns={"mean": "_mean", "std": "_scale"})
-        )
-        self.stats_["_scale"] = self.stats_["_scale"].clip(lower=self.min_scale)
-        df = df.merge(self.stats_, on=self.id_col)
-        df[self.target_col] = (df[self.target_col] - df["_mean"]) / df["_scale"]
-        df = df.drop(columns=["_mean", "_scale"])
-        return df
-
-    def inverse_transform(self, df: pd.DataFrame) -> pd.DataFrame:
-        df = df.merge(self.stats_, on=self.id_col)
-        for col in df.columns.drop([self.id_col, self.time_col, "_mean", "_scale"]):
-            df[col] = df[col] * df["_scale"] + df["_mean"]
-        df = df.drop(columns=["_mean", "_scale"])
-        return df
-
-
-class MeanAbsScaler(BaseTargetTransform):
-    """Scales time series by diving by their mean absolute value."""
-
-    min_scale: float = 1e-2
-
-    def fit_transform(self, df: pd.DataFrame) -> pd.DataFrame:
-        target = df[self.target_col].replace([np.inf, -np.inf], np.nan).abs()
-        self.stats_ = target.groupby(df[self.id_col], sort=False).agg(["mean"]).rename(columns={"mean": "_scale"})
-        self.stats_["_scale"] = self.stats_["_scale"].clip(lower=self.min_scale)
-        df = df.merge(self.stats_, on=self.id_col)
-        df[self.target_col] = df[self.target_col] / df["_scale"]
-        df = df.drop(columns=["_scale"])
-        return df
-
-    def inverse_transform(self, df: pd.DataFrame) -> pd.DataFrame:
-        df = df.merge(self.stats_, on=self.id_col)
-        for col in df.columns.drop([self.id_col, self.time_col, "_scale"]):
-            df[col] = df[col] * df["_scale"]
-        df = df.drop(columns=["_scale"])
-        return df
+MLF_TARGET = "y"
+MLF_ITEMID = "unique_id"
+MLF_TIMESTAMP = "ds"

autogluon/timeseries/models/gluonts/torch/models.py

@@ -66,7 +66,8 @@ class DeepARModel(AbstractGluonTSModel):
     distr_output : gluonts.torch.distributions.DistributionOutput, default = StudentTOutput()
         Distribution to use to evaluate observations and sample predictions
     scaling: bool, default = True
-        Whether to automatically scale the target values
+        If True, mean absolute scaling will be applied to each *context window* during training & prediction.
+        Note that this is different from the `target_scaler` that is applied to the *entire time series*.
     max_epochs : int, default = 100
         Number of epochs the model will be trained for
     batch_size : int, default = 64
@@ -85,6 +86,8 @@ class DeepARModel(AbstractGluonTSModel):
         If True, ``lightning_logs`` directory will NOT be removed after the model finished training.
     """
 
+    # TODO: Replace "scaling: bool" with "window_scaler": {"mean_abs", None} for consistency?
+
     supports_known_covariates = True
     supports_static_features = True
 
@@ -122,7 +125,8 @@ class SimpleFeedForwardModel(AbstractGluonTSModel):
     batch_normalization : bool, default = False
         Whether to use batch normalization
     mean_scaling : bool, default = True
-        Scale the network input by the data mean and the network output by its inverse
+        If True, mean absolute scaling will be applied to each *context window* during training & prediction.
+        Note that this is different from the `target_scaler` that is applied to the *entire time series*.
     max_epochs : int, default = 100
         Number of epochs the model will be trained for
     batch_size : int, default = 64
@@ -254,7 +258,10 @@ class DLinearModel(AbstractGluonTSModel):
     distr_output : gluonts.torch.distributions.DistributionOutput, default = StudentTOutput()
         Distribution to fit.
     scaling : {"mean", "std", None}, default = "mean"
-        Scaling applied to the inputs. One of ``"mean"`` (mean absolute scaling), ``"std"`` (standardization), ``None`` (no scaling).
+        Scaling applied to each *context window* during training & prediction.
+        One of ``"mean"`` (mean absolute scaling), ``"std"`` (standardization), ``None`` (no scaling).
+
+        Note that this is different from the `target_scaler` that is applied to the *entire time series*.
     max_epochs : int, default = 100
         Number of epochs the model will be trained for
     batch_size : int, default = 64
@@ -314,7 +321,10 @@ class PatchTSTModel(AbstractGluonTSModel):
     distr_output : gluonts.torch.distributions.DistributionOutput, default = StudentTOutput()
         Distribution to fit.
     scaling : {"mean", "std", None}, default = "mean"
-        Scaling applied to the inputs. One of ``"mean"`` (mean absolute scaling), ``"std"`` (standardization), ``None`` (no scaling).
+        Scaling applied to each *context window* during training & prediction.
+        One of ``"mean"`` (mean absolute scaling), ``"std"`` (standardization), ``None`` (no scaling).
+
+        Note that this is different from the `target_scaler` that is applied to the *entire time series*.
     max_epochs : int, default = 100
         Number of epochs the model will be trained for
     batch_size : int, default = 64
@@ -477,7 +487,10 @@ class TiDEModel(AbstractGluonTSModel):
     layer_norm : bool, default = False
         Should layer normalization be enabled?
     scaling : {"mean", "std", None}, default = "mean"
-        Scaling applied to the inputs. One of ``"mean"`` (mean absolute scaling), ``"std"`` (standardization), ``None`` (no scaling).
+        Scaling applied to each *context window* during training & prediction.
+        One of ``"mean"`` (mean absolute scaling), ``"std"`` (standardization), ``None`` (no scaling).
+
+        Note that this is different from the `target_scaler` that is applied to the *entire time series*.
     max_epochs : int, default = 100
         Number of epochs the model will be trained for
     batch_size : int, default = 64

autogluon/timeseries/models/local/abstract_local_model.py

@@ -87,6 +87,14 @@ class AbstractLocalModel(AbstractTimeSeriesModel):
         self.time_limit: Optional[float] = None
         self._dummy_forecast: Optional[pd.DataFrame] = None
 
+    @property
+    def allowed_hyperparameters(self) -> List[str]:
+        return (
+            super().allowed_hyperparameters
+            + ["use_fallback_model", "max_ts_length", "n_jobs"]
+            + self.allowed_local_model_args
+        )
+
     def preprocess(self, data: TimeSeriesDataFrame, is_train: bool = False, **kwargs) -> Any:
         if not self._get_tags()["allow_nan"]:
             data = data.fill_missing_values()
@@ -103,8 +111,9 @@ class AbstractLocalModel(AbstractTimeSeriesModel):
 
         unused_local_model_args = []
         local_model_args = {}
+        # TODO: Move filtering logic to AbstractTimeSeriesModel
         for key, value in raw_local_model_args.items():
-            if key in self.allowed_local_model_args:
+            if key in self.allowed_hyperparameters:
                 local_model_args[key] = value
             else:
                 unused_local_model_args.append(key)

autogluon/timeseries/models/multi_window/multi_window_model.py

@@ -13,6 +13,7 @@ from autogluon.timeseries.dataset.ts_dataframe import TimeSeriesDataFrame
 from autogluon.timeseries.models.abstract import AbstractTimeSeriesModel
 from autogluon.timeseries.models.local.abstract_local_model import AbstractLocalModel
 from autogluon.timeseries.splitter import AbstractWindowSplitter, ExpandingWindowSplitter
+from autogluon.timeseries.transforms import LocalTargetScaler
 
 logger = logging.getLogger(__name__)
 
@@ -32,6 +33,8 @@ class MultiWindowBacktestingModel(AbstractTimeSeriesModel):
         kwargs used to initialize model_base if model_base is a class.
     """
 
+    # TODO: Remove the MultiWindowBacktestingModel class, move the logic to AbstractTimeSeriesTrainer
+
     def __init__(
         self,
         model_base: Union[AbstractTimeSeriesModel, Type[AbstractTimeSeriesModel]],
@@ -82,6 +85,10 @@ class MultiWindowBacktestingModel(AbstractTimeSeriesModel):
     def get_minimum_resources(self, is_gpu_available: bool = False) -> bool:
         return self._get_model_base().get_minimum_resources(is_gpu_available)
 
+    def _create_target_scaler(self) -> Optional[LocalTargetScaler]:
+        # Do not use scaler in the MultiWindowModel to avoid duplication; it will be created in the inner model
+        return None
+
     def _fit(
         self,
         train_data: TimeSeriesDataFrame,

autogluon/timeseries/transforms/__init__.py

@@ -0,0 +1,8 @@
+from .scaler import (
+    LocalStandardScaler,
+    LocalMinMaxScaler,
+    LocalMeanAbsScaler,
+    LocalRobustScaler,
+    LocalTargetScaler,
+    get_target_scaler_from_name
+)

autogluon/timeseries/transforms/scaler.py

@@ -0,0 +1,132 @@
+from typing import Literal, Optional, Tuple, Union
+
+import numpy as np
+import pandas as pd
+
+from autogluon.timeseries.dataset.ts_dataframe import ITEMID, TimeSeriesDataFrame
+
+
+class LocalTargetScaler:
+    """Applies an affine transformation (x - loc) / scale independently to each time series in the dataset."""
+
+    def __init__(
+        self,
+        target: str = "target",
+        min_scale: float = 1e-2,
+    ):
+        self.target = target
+        self.min_scale = min_scale
+        self.loc: Optional[pd.Series] = None
+        self.scale: Optional[pd.Series] = None
+
+    def _compute_loc_scale(self, target_series: pd.Series) -> Tuple[Optional[pd.Series], Optional[pd.Series]]:
+        raise NotImplementedError
+
+    def fit_transform(self, data: TimeSeriesDataFrame) -> TimeSeriesDataFrame:
+        return self.fit(data=data).transform(data=data)
+
+    def fit(self, data: TimeSeriesDataFrame) -> "LocalTargetScaler":
+        target_series = data[self.target].replace([np.inf, -np.inf], np.nan)
+        self.loc, self.scale = self._compute_loc_scale(target_series)
+        if self.loc is not None:
+            self.loc = self.loc.replace([np.inf, -np.inf], np.nan).fillna(0.0)
+        if self.scale is not None:
+            self.scale = self.scale.clip(lower=self.min_scale).replace([np.inf, -np.inf], np.nan).fillna(1.0)
+        return self
+
+    def _reindex_loc_scale(self, item_index: pd.Index) -> Tuple[Union[np.ndarray, float], Union[np.ndarray, float]]:
+        """Reindex loc and scale parameters for the given item_ids and convert them to an array-like."""
+        if self.loc is not None:
+            loc = self.loc.reindex(item_index).to_numpy()
+        else:
+            loc = 0.0
+        if self.scale is not None:
+            scale = self.scale.reindex(item_index).to_numpy()
+        else:
+            scale = 1.0
+        return loc, scale
+
+    def transform(self, data: TimeSeriesDataFrame) -> TimeSeriesDataFrame:
+        """Apply scaling to the target column in the dataframe."""
+        loc, scale = self._reindex_loc_scale(item_index=data.index.get_level_values(ITEMID))
+        return data.assign(**{self.target: (data[self.target] - loc) / scale})
+
+    def inverse_transform(self, predictions: TimeSeriesDataFrame) -> TimeSeriesDataFrame:
+        """Apply inverse scaling to all columns in the predictions dataframe."""
+        loc, scale = self._reindex_loc_scale(item_index=predictions.index.get_level_values(ITEMID))
+        return predictions.assign(**{col: predictions[col] * scale + loc for col in predictions.columns})
+
+
+class LocalStandardScaler(LocalTargetScaler):
+    """Applies standard scaling to each time series in the dataset.
+
+    The resulting affine transformation is (x - loc) / scale, where scale = std(x), loc = mean(x).
+    """
+
+    def _compute_loc_scale(self, target_series: pd.Series) -> Tuple[pd.Series, pd.Series]:
+        stats = target_series.groupby(level=ITEMID, sort=False).agg(["mean", "std"])
+        return stats["mean"], stats["std"]
+
+
+class LocalMeanAbsScaler(LocalTargetScaler):
+    """Applies mean absolute scaling to each time series in the dataset."""
+
+    def _compute_loc_scale(self, target_series: pd.Series) -> Tuple[pd.Series, pd.Series]:
+        scale = target_series.abs().groupby(level=ITEMID, sort=False).agg("mean")
+        return None, scale
+
+
+class LocalMinMaxScaler(LocalTargetScaler):
+    """Applies min/max scaling to each time series in the dataset.
+
+    The resulting affine transformation is (x - loc) / scale, where scale = max(x) - min(x), loc = min(x) / scale.
+    """
+
+    def _compute_loc_scale(self, target_series: pd.Series) -> Tuple[pd.Series, pd.Series]:
+        stats = target_series.abs().groupby(level=ITEMID, sort=False).agg(["min", "max"])
+        scale = (stats["max"] - stats["min"]).clip(lower=self.min_scale)
+        loc = stats["min"] / scale
+        return loc, scale
+
+
+class LocalRobustScaler(LocalTargetScaler):
+    """Applies a robust scaler based on the interquartile range. Less sensitive to outliers compared to other scaler.
+
+    The resulting affine transformation is (x - loc) / scale, where scale = quantile(x, 0.75) - quantile(x, 0.25), loc = median(x).
+    """
+
+    def __init__(
+        self,
+        target: str = "target",
+        min_scale: float = 1e-2,
+        **kwargs,
+    ):
+        super().__init__(target=target, min_scale=min_scale)
+        self.q_min = 0.25
+        self.q_max = 0.75
+        assert 0 < self.q_min < self.q_max < 1
+
+    def _compute_loc_scale(self, target_series: pd.Series) -> Tuple[pd.Series, pd.Series]:
+        grouped = target_series.groupby(level=ITEMID, sort=False)
+        loc = grouped.median()
+        lower = grouped.quantile(self.q_min)
+        upper = grouped.quantile(self.q_max)
+        scale = upper - lower
+        return loc, scale
+
+
+AVAILABLE_SCALERS = {
+    "standard": LocalStandardScaler,
+    "mean_abs": LocalMeanAbsScaler,
+    "min_max": LocalMinMaxScaler,
+    "robust": LocalRobustScaler,
+}
+
+
+def get_target_scaler_from_name(
+    name: Literal["standard", "mean_abs", "min_max", "robust"], **scaler_kwargs
+) -> LocalTargetScaler:
+    """Get LocalTargetScaler object from a string."""
+    if name not in AVAILABLE_SCALERS:
+        raise KeyError(f"Scaler type {name} not supported. Available scalers: {list(AVAILABLE_SCALERS)}")
+    return AVAILABLE_SCALERS[name](**scaler_kwargs)

autogluon/timeseries/version.py

@@ -1,3 +1,3 @@
 """This is the autogluon version file."""
-__version__ = '1.1.2b20240925'
+__version__ = '1.1.2b20240926'
 __lite__ = False

{autogluon.timeseries-1.1.2b20240925.dist-info → autogluon.timeseries-1.1.2b20240926.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: autogluon.timeseries
-Version: 1.1.2b20240925
+Version: 1.1.2b20240926
 Summary: Fast and Accurate ML in 3 Lines of Code
 Home-page: https://github.com/autogluon/autogluon
 Author: AutoGluon Community
@@ -46,15 +46,16 @@ Requires-Dist: accelerate<0.22.0,>=0.21.0
 Requires-Dist: gluonts==0.15.1
 Requires-Dist: networkx<4,>=3.0
 Requires-Dist: statsforecast<1.8,>=1.7.0
-Requires-Dist: mlforecast<0.10.1,>=0.10.0
-Requires-Dist: utilsforecast<=0.1.9
+Requires-Dist: mlforecast==0.13.4
+Requires-Dist: utilsforecast<0.2.5,>=0.2.3
+Requires-Dist: coreforecast==0.0.12
 Requires-Dist: fugue>=0.9.0
 Requires-Dist: tqdm<5,>=4.38
 Requires-Dist: orjson~=3.9
 Requires-Dist: tensorboard<3,>=2.9
-Requires-Dist: autogluon.core[raytune]==1.1.2b20240925
-Requires-Dist: autogluon.common==1.1.2b20240925
-Requires-Dist: autogluon.tabular[catboost,lightgbm,xgboost]==1.1.2b20240925
+Requires-Dist: autogluon.core[raytune]==1.1.2b20240926
+Requires-Dist: autogluon.common==1.1.2b20240926
+Requires-Dist: autogluon.tabular[catboost,lightgbm,xgboost]==1.1.2b20240926
 Provides-Extra: all
 Requires-Dist: optimum[onnxruntime]<1.19,>=1.17; extra == "all"
 Provides-Extra: chronos-onnx

{autogluon.timeseries-1.1.2b20240925.dist-info → autogluon.timeseries-1.1.2b20240926.dist-info}/RECORD

@@ -1,10 +1,10 @@
-autogluon.timeseries-1.1.2b20240925-py3.8-nspkg.pth,sha256=cQGwpuGPqg1GXscIwt-7PmME1OnSpD-7ixkikJ31WAY,554
+autogluon.timeseries-1.1.2b20240926-py3.8-nspkg.pth,sha256=cQGwpuGPqg1GXscIwt-7PmME1OnSpD-7ixkikJ31WAY,554
 autogluon/timeseries/__init__.py,sha256=_CrLLc1fkjen7UzWoO0Os8WZoHOgvZbHKy46I8v_4k4,304
 autogluon/timeseries/evaluator.py,sha256=l642tYfTHsl8WVIq_vV6qhgAFVFr9UuZD7gLra3A_Kc,250
 autogluon/timeseries/learner.py,sha256=NXhftyqMD8Bl1QHIBN82UKP0UlCV_ACughZqkmMf4oY,14043
 autogluon/timeseries/predictor.py,sha256=NFe-y1H8987Rlnjcr4GqAxL7ivFaMuu94XWWiZrp9Uc,84351
 autogluon/timeseries/splitter.py,sha256=eghGwAAN2_cxGk5aJBILgjGWtLzjxJcytMy49gg_q18,3061
-autogluon/timeseries/version.py,sha256=O9QEUJv0UF7vl2iZXmooSPWoH_6JaKWyK14XJQJkIJA,90
+autogluon/timeseries/version.py,sha256=Li6mwhhJy16eLGxm4jg4RzHnSfTH_RuoVZ576yp1Cx8,90
 autogluon/timeseries/configs/__init__.py,sha256=BTtHIPCYeGjqgOcvqb8qPD4VNX-ICKOg6wnkew1cPOE,98
 autogluon/timeseries/configs/presets_configs.py,sha256=94-yL9teDHKs2irWjP3kpewI7FE1ChYCgEgz9XHJ6gc,1965
 autogluon/timeseries/dataset/__init__.py,sha256=UvnhAN5tjgxXTHoZMQDy64YMDj4Xxa68yY7NP4vAw0o,81
@@ -17,11 +17,12 @@ autogluon/timeseries/metrics/utils.py,sha256=eJ63TCR-UwbeJ1c2Qm7B2q-8B3sFthPgioo
 autogluon/timeseries/models/__init__.py,sha256=WKV7DIpJkrwEj0cUfscESp67Ydap9hAqaNTYvgi2EIA,1303
 autogluon/timeseries/models/presets.py,sha256=7ORBU-7fCwwYlpXaWCXEfNx0pss3mvB6KGSsQ1kyw2k,11673
 autogluon/timeseries/models/abstract/__init__.py,sha256=wvDsQAZIV0N3AwBeMaGItoQ82trEfnT-nol2AAOIxBg,102
-autogluon/timeseries/models/abstract/abstract_timeseries_model.py,sha256=MvLF529b3fo0icgle-qmS0oce-ftiiQ1jPBLnY-39fk,23435
+autogluon/timeseries/models/abstract/abstract_timeseries_model.py,sha256=siy-OW4zflN61-pnuhvYawDvchm3zXb1ta8HUDLxhWY,24793
 autogluon/timeseries/models/abstract/model_trial.py,sha256=ENPg_7nsdxIvaNM0o0UShZ3x8jFlRmwRc5m0fGPC0TM,3720
 autogluon/timeseries/models/autogluon_tabular/__init__.py,sha256=r9i6jWcyeLHYClkcMSKRVsfrkBUMxpDrTATNTBc_qgQ,136
-autogluon/timeseries/models/autogluon_tabular/mlforecast.py,sha256=Px5_VuQx8f74CpQYuClijtyK-yJLkNW7fSjCZrmJZ0s,32815
-autogluon/timeseries/models/autogluon_tabular/utils.py,sha256=4-gTrBtizxeMVQlsuscugPqw9unaXWXhS1TVVssfzYY,2125
+autogluon/timeseries/models/autogluon_tabular/mlforecast.py,sha256=C1WVcuNlTcqo_qGm3v0uPpraO06mdVnBNeflPbCPjNQ,32861
+autogluon/timeseries/models/autogluon_tabular/transforms.py,sha256=FozTzwcp1QjevEhrMLXsJHy8fymOcq1146oX4Al60wg,2517
+autogluon/timeseries/models/autogluon_tabular/utils.py,sha256=Fn3Vu_Q0PCtEUbtNgLp1xIblg7dOdpFlF3W5kLHgruI,63
 autogluon/timeseries/models/chronos/__init__.py,sha256=wT77HzTtmQxW3sw2k0mA5Ot6PSHivX-Uvn5fjM05EU4,60
 autogluon/timeseries/models/chronos/model.py,sha256=vnKzRExX-2CAv9yD0HeeLRF4oY9HnZwrRIAEfLbAMtg,14703
 autogluon/timeseries/models/chronos/pipeline.py,sha256=vR1LbMkWFKDX6WZBcAtsGQYnRq1vkV935omTj3Zyr9U,20788
@@ -32,17 +33,19 @@ autogluon/timeseries/models/ensemble/greedy_ensemble.py,sha256=5HvZuW5osgsZg3V69
 autogluon/timeseries/models/gluonts/__init__.py,sha256=asC1PTj4j9xMbilvk1IT1julnpeoKbv5ZNuAR6-DFgA,361
 autogluon/timeseries/models/gluonts/abstract_gluonts.py,sha256=X4KChuSVSoxLOcrto1SgwAgiHeCuE5jFOaX8GxdBTeg,34017
 autogluon/timeseries/models/gluonts/torch/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-autogluon/timeseries/models/gluonts/torch/models.py,sha256=5fp2yEyTvMVDm-jQEUYB4ugLkVDcd364NBUjmePltO8,24058
+autogluon/timeseries/models/gluonts/torch/models.py,sha256=85MWDXPwDncGwLijkm-K1tS-05LvGq4Xl-WbbIcYCO8,24906
 autogluon/timeseries/models/local/__init__.py,sha256=JyckWWgMG1BTIWJqFTW6e1O-eb0LPPOwtXwmb1ErohQ,756
-autogluon/timeseries/models/local/abstract_local_model.py,sha256=Ge4X4FgyYHsFU5h9q7mSVlEXKKJtyGqckjPJ4PXx3A0,11917
+autogluon/timeseries/models/local/abstract_local_model.py,sha256=af3GFfUIGnVNzzZJ-WI61lw83lDFfgB0AfGxmkb-t_4,12226
 autogluon/timeseries/models/local/naive.py,sha256=iwRcFMFmJKPWPbD9TWaIUS51oav69F_VAp6-jb_5SUE,7249
 autogluon/timeseries/models/local/npts.py,sha256=Bp74doKnfpGE8ywP4FWOCI_RwRMsmgocYDfGtq764DA,4143
 autogluon/timeseries/models/local/statsforecast.py,sha256=79swW7g7bn1CmuGY79i7r0uj0QZr6WLIfH_x3p1FTDA,32742
 autogluon/timeseries/models/multi_window/__init__.py,sha256=Bq7AT2Jxdd4WNqmjTdzeqgNiwn1NCyWp4tBIWaM-zfI,60
-autogluon/timeseries/models/multi_window/multi_window_model.py,sha256=HiujLv8MJ31fWxRM5iXG2PzobFn4Mus0nJPu0MP2Rw4,11374
+autogluon/timeseries/models/multi_window/multi_window_model.py,sha256=EAXzoQo96zTPNz9BTYDmV1878OVKb9F6h39y386N3zU,11740
 autogluon/timeseries/trainer/__init__.py,sha256=lxiOT-Gc6BEnr_yWQqra85kEngeM_wtH2SCaRbmC_qE,170
 autogluon/timeseries/trainer/abstract_trainer.py,sha256=hZI4QcsFvU1gxP2yv_DRCIMlc6q02ptR7UDA9EgJPoM,60409
 autogluon/timeseries/trainer/auto_trainer.py,sha256=psJFZBwWWPlLjNwAgvO4OUJXsRW1sTN2YS9a4pdoeoE,3344
+autogluon/timeseries/transforms/__init__.py,sha256=lzDavxdgGIz5m_DmSpNa9ewNU9Evndam3YXfOEk6kwY,174
+autogluon/timeseries/transforms/scaler.py,sha256=30JrAnZwj58ntes-YP1H_XmeVLGtFepjWnRzPQQ-t4k,5352
 autogluon/timeseries/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 autogluon/timeseries/utils/features.py,sha256=hEir-2lU8fvHjt5r_LG9tLZEk5wNdRdeLRE7qF5z3_Y,19585
 autogluon/timeseries/utils/forecast.py,sha256=p0WKM9Q0nLAwwmCgYZI1zi9mCOWXWJfllEt2lPRQl4M,1882
@@ -52,11 +55,11 @@ autogluon/timeseries/utils/datetime/base.py,sha256=3NdsH3NDq4cVAOSoy3XpaNixyNlbj
 autogluon/timeseries/utils/datetime/lags.py,sha256=GoLtvcZ8oKb3QkoBJ9E59LSPLOP7Qjxrr2UmMSZgjyw,5909
 autogluon/timeseries/utils/datetime/seasonality.py,sha256=h_4w00iEytAz_N_EpCENQ8RCXy7KQITczrYjBgVqWkQ,764
 autogluon/timeseries/utils/datetime/time_features.py,sha256=PAXbYbQ0z_5GFbkxSNi41zLY_2-U3x0Ynm1m_WhdtGc,2572
-autogluon.timeseries-1.1.2b20240925.dist-info/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
-autogluon.timeseries-1.1.2b20240925.dist-info/METADATA,sha256=iTfUioN_ZC83-CqEQGJACJdqEl2GfRj1iGJ9RLDsIw0,12370
-autogluon.timeseries-1.1.2b20240925.dist-info/NOTICE,sha256=7nPQuj8Kp-uXsU0S5so3-2dNU5EctS5hDXvvzzehd7E,114
-autogluon.timeseries-1.1.2b20240925.dist-info/WHEEL,sha256=eOLhNAGa2EW3wWl_TU484h7q1UNgy0JXjjoqKoxAAQc,92
-autogluon.timeseries-1.1.2b20240925.dist-info/namespace_packages.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
-autogluon.timeseries-1.1.2b20240925.dist-info/top_level.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
-autogluon.timeseries-1.1.2b20240925.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-autogluon.timeseries-1.1.2b20240925.dist-info/RECORD,,
+autogluon.timeseries-1.1.2b20240926.dist-info/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
+autogluon.timeseries-1.1.2b20240926.dist-info/METADATA,sha256=6EFhuCNkwsbg9HTtvJLuhfLIYbdUI5BW5HuPAxTLm40,12405
+autogluon.timeseries-1.1.2b20240926.dist-info/NOTICE,sha256=7nPQuj8Kp-uXsU0S5so3-2dNU5EctS5hDXvvzzehd7E,114
+autogluon.timeseries-1.1.2b20240926.dist-info/WHEEL,sha256=eOLhNAGa2EW3wWl_TU484h7q1UNgy0JXjjoqKoxAAQc,92
+autogluon.timeseries-1.1.2b20240926.dist-info/namespace_packages.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
+autogluon.timeseries-1.1.2b20240926.dist-info/top_level.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
+autogluon.timeseries-1.1.2b20240926.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+autogluon.timeseries-1.1.2b20240926.dist-info/RECORD,,