autogluon.timeseries 1.3.2b20250712__py3-none-any.whl → 1.4.1b20251116__py3-none-any.whl

autogluon/timeseries/models/autogluon_tabular/per_step.py

@@ -2,29 +2,29 @@ import logging
 import math
 import os
 import time
-from typing import Any, Callable, Dict, List, Optional, Type
+from typing import Any, Callable, Literal, Optional, Type
 
 import numpy as np
 import pandas as pd
+import scipy.stats
 from joblib import Parallel, cpu_count, delayed
 
+from autogluon.common.loaders import load_pkl
+from autogluon.common.savers import save_pkl
 from autogluon.common.utils.pandas_utils import get_approximate_df_mem_usage
 from autogluon.common.utils.resource_utils import ResourceManager
-from autogluon.core.constants import QUANTILE
+from autogluon.core.constants import QUANTILE, REGRESSION
 from autogluon.tabular.models import AbstractModel as AbstractTabularModel
 from autogluon.tabular.registry import ag_model_registry
 from autogluon.timeseries import TimeSeriesDataFrame
-from autogluon.timeseries.dataset.ts_dataframe import ITEMID, TIMESTAMP
 from autogluon.timeseries.models.abstract import AbstractTimeSeriesModel
 from autogluon.timeseries.utils.datetime import get_lags_for_frequency, get_time_features_for_frequency
-from autogluon.timeseries.utils.warning_filters import set_loggers_level
+from autogluon.timeseries.utils.warning_filters import set_loggers_level, warning_filter
 
 from .utils import MLF_ITEMID, MLF_TARGET, MLF_TIMESTAMP
 
 logger = logging.getLogger(__name__)
 
-DUMMY_FREQ = "D"
-
 
 class PerStepTabularModel(AbstractTimeSeriesModel):
     """Fit a separate tabular regression model for each time step in the forecast horizon.
@@ -36,43 +36,53 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
     - known covariates (if available)
     - static features of each item (if available)
 
-    This model is typically much slower to fit compared to other tabular forecasting models.
+    This model is typically slower to fit compared to other tabular forecasting models.
+
+    If ``eval_metric.needs_quantile``, the tabular regression models will be trained with ``"quantile"`` problem type.
+    Otherwise, the models will be trained with ``"regression"`` problem type, and dummy quantiles will be
+    obtained by assuming that the residuals follow zero-mean normal distribution.
 
     This model uses `mlforecast <https://github.com/Nixtla/mlforecast>`_ under the hood for efficient preprocessing,
-    but the implementation of the per-step forecasting strategy is different from the `max_horizon` in `mlforecast`.
+    but the implementation of the per-step forecasting strategy is different from the ``max_horizon`` in ``mlforecast``.
 
 
     Other Parameters
     ----------------
-    trailing_lags : List[int], default = None
+    trailing_lags : list[int], default = None
         Trailing window lags of the target that will be used as features for predictions.
-        Trailing lags are shifted per forecast step: model for step `h` uses `[lag+h for lag in trailing_lags]`.
-        If None, defaults to [1, 2, ..., 12].
-    seasonal_lags: List[int], default = None
+        Trailing lags are shifted per forecast step: model for step ``h`` uses ``[lag+h for lag in trailing_lags]``.
+        If None, defaults to ``[1, 2, ..., 12]``.
+    seasonal_lags : list[int], default = None
         Seasonal lags of the target used as features. Unlike trailing lags, seasonal lags are not shifted
-        but filtered by availability: model for step `h` uses `[lag for lag in seasonal_lags if lag > h]`.
+        but filtered by availability: model for step ``h`` uses ``[lag for lag in seasonal_lags if lag > h]``.
         If None, determined automatically based on data frequency.
-    date_features : List[Union[str, Callable]], default = None
+    date_features : list[Union[str, Callable]], default = None
         Features computed from the dates. Can be pandas date attributes or functions that will take the dates as input.
         If None, will be determined automatically based on the frequency of the data.
     target_scaler : {"standard", "mean_abs", "min_max", "robust", None}, default = "mean_abs"
         Scaling applied to each time series.
     model_name : str, default = "CAT"
-        Name of the tabular regression model. See `autogluon.tabular.registry.ag_model_registry` or
+        Name of the tabular regression model. See ``autogluon.tabular.registry.ag_model_registry`` or
         `the documentation <https://auto.gluon.ai/stable/api/autogluon.tabular.models.html>`_ for the list of available
         tabular models.
-    model_hyperparameters : Dict[str, Any], optional
+    model_hyperparameters : dict[str, Any], optional
         Hyperparameters passed to the tabular regression model.
+    validation_fraction : float or None, default = 0.1
+        Fraction of the training data to use for validation. If None or 0.0, no validation set is created.
+        Validation set contains the most recent observations (chronologically). Must be between 0.0 and 1.0.
     max_num_items : int or None, default = 20_000
         If not None, the model will randomly select this many time series for training and validation.
     max_num_samples : int or None, default = 1_000_000
-        If not None, training dataset passed to TabularPredictor will contain at most this many rows (starting from the
-        end of each time series).
+        If not None, training dataset passed to the tabular regression model will contain at most this many rows
+        (starting from the end of each time series).
     n_jobs : int or None, default = None
         Number of parallel jobs for fitting models across forecast horizons.
         If None, automatically determined based on available memory to prevent OOM errors.
     """
 
+    ag_priority = 70
+    _dummy_freq = "D"
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         # We save the relative paths to per-step models. Each worker process independently saves/loads the model.
@@ -83,11 +93,11 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
         self._date_features: list[Callable]
         self._model_cls: Type[AbstractTabularModel]
         self._n_jobs: int
-        self._non_boolean_real_covariates: List[str] = []
+        self._non_boolean_real_covariates: list[str] = []
         self._max_ts_length: Optional[int] = None
 
     @property
-    def allowed_hyperparameters(self) -> List[str]:
+    def allowed_hyperparameters(self) -> list[str]:
         # TODO: Differencing is currently not supported because it greatly complicates the preprocessing logic
         return super().allowed_hyperparameters + [
             "trailing_lags",
@@ -104,7 +114,11 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
 
     @property
     def _ag_to_nixtla(self) -> dict:
-        return {self.target: MLF_TARGET, ITEMID: MLF_ITEMID, TIMESTAMP: MLF_TIMESTAMP}
+        return {
+            self.target: MLF_TARGET,
+            TimeSeriesDataFrame.ITEMID: MLF_ITEMID,
+            TimeSeriesDataFrame.TIMESTAMP: MLF_TIMESTAMP,
+        }
 
     def _get_default_hyperparameters(self):
         return {
@@ -116,13 +130,16 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
             "max_num_items": 20_000,
         }
 
-    @staticmethod
+    @classmethod
     def _fit_single_model(
+        cls,
         train_df: pd.DataFrame,
         path_root: str,
         step: int,
         model_cls: Type[AbstractTabularModel],
         model_hyperparameters: dict,
+        problem_type: Literal["quantile", "regression"],
+        eval_metric: str,
         validation_fraction: Optional[float],
         quantile_levels: list[float],
         lags: list[int],
@@ -135,13 +152,15 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
 
         start_time = time.monotonic()
 
-        mlf = MLForecast(models=[], freq=DUMMY_FREQ, lags=lags, date_features=date_features)
+        mlf = MLForecast(models=[], freq=cls._dummy_freq, lags=lags, date_features=date_features)
 
-        features_df = mlf.preprocess(train_df, static_features=[], dropna=False)
+        with warning_filter():
+            features_df = mlf.preprocess(train_df, static_features=[], dropna=False)
         del train_df
         del mlf
         # Sort chronologically for efficient train/test split
         features_df = features_df.sort_values(by=MLF_TIMESTAMP)
+        item_ids = features_df[MLF_ITEMID]
         X = features_df.drop(columns=[MLF_ITEMID, MLF_TIMESTAMP, MLF_TARGET])
         y = features_df[MLF_TARGET]
         del features_df
@@ -162,14 +181,16 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
 
         elapsed = time.monotonic() - start_time
         time_left = time_limit - elapsed if time_limit is not None else None
+        if problem_type == QUANTILE:
+            model_hyperparameters = model_hyperparameters | {"ag.quantile_levels": quantile_levels}
         try:
             with set_loggers_level(regex=r"^autogluon.tabular.*", level=logging.ERROR):
                 model = model_cls(
                     path=os.path.join(path_root, f"step_{step}"),
                     name=model_cls.__name__,  # explicitly provide name to avoid warnings
-                    problem_type=QUANTILE,
-                    eval_metric="pinball_loss",
-                    hyperparameters={**model_hyperparameters, "ag.quantile_levels": quantile_levels},
+                    problem_type=problem_type,
+                    eval_metric=eval_metric,
+                    hyperparameters=model_hyperparameters,
                 )
                 model.fit(
                     X=X,
@@ -184,6 +205,9 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
         except Exception as e:
             raise RuntimeError(f"Failed when fitting model for {step=}") from e
         model.save()
+        if problem_type == REGRESSION:
+            residuals_std = pd.Series((model.predict(X) - y) ** 2).groupby(item_ids).mean() ** 0.5
+            save_pkl.save(cls._get_residuals_std_path(model.path), residuals_std)
         relative_path = os.path.relpath(path=model.path, start=path_root)
         return relative_path
 
@@ -225,7 +249,7 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
                     self._non_boolean_real_covariates.append(col)
 
         if len(self._non_boolean_real_covariates) > 0:
-            item_ids = data.index.get_level_values(level=ITEMID)
+            item_ids = data.index.get_level_values(level=TimeSeriesDataFrame.ITEMID)
             scale_per_column: dict[str, pd.Series] = {}
             columns_grouped = data[self._non_boolean_real_covariates].abs().groupby(item_ids)
             for col in self._non_boolean_real_covariates:
@@ -256,7 +280,11 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
         train_df = train_data.to_data_frame().reset_index()
         if train_data.static_features is not None:
             train_df = pd.merge(
-                left=train_df, right=train_data.static_features, left_on=ITEMID, right_index=True, how="left"
+                left=train_df,
+                right=train_data.static_features,
+                left_on=TimeSeriesDataFrame.ITEMID,
+                right_index=True,
+                how="left",
             )
         train_df = train_df.rename(columns=self._ag_to_nixtla)
         train_df = train_df.assign(**{MLF_TARGET: train_df[MLF_TARGET].fillna(float("inf"))})
@@ -264,10 +292,10 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
 
     @staticmethod
     def _get_lags_for_step(
-        trailing_lags: List[int],
-        seasonal_lags: List[int],
+        trailing_lags: list[int],
+        seasonal_lags: list[int],
         step: int,
-    ) -> List[int]:
+    ) -> list[int]:
         """Get the list of lags that can be used by the model for the given step."""
         shifted_trailing_lags = [lag + step for lag in trailing_lags]
         # Only keep lags that are available for model predicting `step` values ahead at prediction time
@@ -313,13 +341,8 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
             date_features = get_time_features_for_frequency(self.freq)
         self._date_features = date_features
 
-        self._model_cls = ag_model_registry.key_to_cls(model_params["model_name"])
-        supported_problem_types = self._model_cls.supported_problem_types()
-        if supported_problem_types is not None and QUANTILE not in supported_problem_types:
-            raise ValueError(
-                f"Chosen model_name='{model_params['model_name']}' cannot be used by {self.name} because it does not "
-                f"support problem_type='quantile' ({supported_problem_types=})"
-            )
+        model_name = model_params["model_name"]
+        self._model_cls = ag_model_registry.key_to_cls(model_name)
         model_hyperparameters = model_params["model_hyperparameters"]
         # User-provided n_jobs takes priority over the automatic estimate
         if model_params.get("n_jobs") is not None:
@@ -339,18 +362,35 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
             time_limit_per_model = time_limit / math.ceil(self.prediction_length / n_jobs)
         else:
             time_limit_per_model = None
+
+        if self.eval_metric.needs_quantile:
+            problem_type = QUANTILE
+            eval_metric = "pinball_loss"
+        else:
+            problem_type = REGRESSION
+            eval_metric = self.eval_metric.equivalent_tabular_regression_metric or "mean_absolute_error"
+
+        supported_problem_types = self._model_cls.supported_problem_types()
+        if supported_problem_types is not None and problem_type not in supported_problem_types:
+            raise ValueError(
+                f"Chosen model_name='{model_name}' cannot be used by {self.name} with eval_metric={self.eval_metric}"
+                f"because {model_name} does not support problem_type={problem_type} ({supported_problem_types=})"
+            )
         model_fit_kwargs = dict(
             train_df=train_df,
             path_root=self.path,
             model_cls=self._model_cls,
             quantile_levels=self.quantile_levels,
             validation_fraction=model_params["validation_fraction"],
+            problem_type=problem_type,
+            eval_metric=eval_metric,
             date_features=self._date_features,
             time_limit=time_limit_per_model,
             num_cpus=num_cpus_per_model,
             model_hyperparameters=model_hyperparameters.copy(),
             verbosity=verbosity - 1,
         )
+
         logger.debug(f"Fitting models in parallel with {n_jobs=}, {num_cpus_per_model=}, {time_limit_per_model=}")
         self._relative_paths_to_models = Parallel(n_jobs=n_jobs)(  # type: ignore
             delayed(self._fit_single_model)(
@@ -363,12 +403,19 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
             for step in range(self.prediction_length)
         )
 
-    @staticmethod
+    @classmethod
+    def _get_residuals_std_path(cls, model_path: str) -> str:
+        """Path to the pd.Series storing the standard deviation of residuals for each item_id."""
+        return os.path.join(model_path, "residuals_std.pkl")
+
+    @classmethod
     def _predict_with_single_model(
+        cls,
         full_df: pd.DataFrame,
         path_to_model: str,
         model_cls: Type[AbstractTabularModel],
         step: int,
+        quantile_levels: list[float],
         prediction_length: int,
         lags: list[int],
         date_features: list[Callable],
@@ -377,14 +424,15 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
 
         Returns
         -------
-        predictions :
+        predictions
             Predictions of the model for the given step. Shape: (num_items, len(quantile_levels)).
         """
         from mlforecast import MLForecast
 
-        mlf = MLForecast(models=[], freq=DUMMY_FREQ, lags=lags, date_features=date_features)
+        mlf = MLForecast(models=[], freq=cls._dummy_freq, lags=lags, date_features=date_features)
 
-        features_df = mlf.preprocess(full_df, static_features=[], dropna=False)
+        with warning_filter():
+            features_df = mlf.preprocess(full_df, static_features=[], dropna=False)
         del mlf
 
         end_idx_per_item = np.cumsum(features_df[MLF_ITEMID].value_counts(sort=False).to_numpy(dtype="int32"))
@@ -395,12 +443,19 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
             logger.error(f"Could not load model for {step=} from {path_to_model}")
             raise
         predictions = model.predict(features_for_step)
+        if model.problem_type == REGRESSION:
+            predictions = np.tile(predictions[:, None], (1, len(quantile_levels)))
+            residuals_std: pd.Series = load_pkl.load(cls._get_residuals_std_path(model.path))
+            item_ids = features_for_step[MLF_ITEMID]
+            residuals_repeated = residuals_std.reindex(item_ids).fillna(residuals_std.mean()).to_numpy()
+            for i, q in enumerate(quantile_levels):
+                predictions[:, i] += scipy.stats.norm.ppf(q) * residuals_repeated
         return predictions
 
     def _predict(
         self,
         data: TimeSeriesDataFrame,
-        known_covariates: TimeSeriesDataFrame | None = None,
+        known_covariates: Optional[TimeSeriesDataFrame] = None,
         **kwargs,
     ) -> TimeSeriesDataFrame:
         if known_covariates is not None:
@@ -414,7 +469,9 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
             full_df = full_df.slice_by_timestep(-(self._max_ts_length + self.prediction_length), None)
         full_df = full_df.to_data_frame().reset_index()
         if data.static_features is not None:
-            full_df = pd.merge(full_df, data.static_features, left_on=ITEMID, right_index=True, how="left")
+            full_df = pd.merge(
+                full_df, data.static_features, left_on=TimeSeriesDataFrame.ITEMID, right_index=True, how="left"
+            )
 
         full_df = (
             full_df.rename(columns=self._ag_to_nixtla)
@@ -425,6 +482,7 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
 
         model_predict_kwargs = dict(
             full_df=full_df,
+            quantile_levels=self.quantile_levels,
             prediction_length=self.prediction_length,
             model_cls=self._model_cls,
             date_features=self._date_features,
@@ -449,5 +507,5 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
         predictions["mean"] = predictions["0.5"]
         return TimeSeriesDataFrame(predictions)
 
-    def _more_tags(self) -> Dict[str, Any]:
+    def _more_tags(self) -> dict[str, Any]:
         return {"allow_nan": True, "can_refit_full": True}

autogluon/timeseries/models/autogluon_tabular/transforms.py

@@ -8,11 +8,7 @@ from mlforecast.target_transforms import (
     _BaseGroupedArrayTargetTransform,
 )
 
-from autogluon.timeseries.dataset.ts_dataframe import (
-    ITEMID,
-    TIMESTAMP,
-    TimeSeriesDataFrame,
-)
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.transforms.target_scaler import TargetScaler, get_target_scaler
 
 from .utils import MLF_ITEMID, MLF_TIMESTAMP
@@ -26,11 +22,17 @@ class MLForecastScaler(BaseTargetTransform):
 
     def _df_to_tsdf(self, df: pd.DataFrame) -> TimeSeriesDataFrame:
         return TimeSeriesDataFrame(
-            df.rename(columns={self.id_col: ITEMID, self.time_col: TIMESTAMP}).set_index([ITEMID, TIMESTAMP])
+            df.rename(
+                columns={self.id_col: TimeSeriesDataFrame.ITEMID, self.time_col: TimeSeriesDataFrame.TIMESTAMP}
+            ).set_index([TimeSeriesDataFrame.ITEMID, TimeSeriesDataFrame.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})
+        return (
+            pd.DataFrame(ts_df)
+            .reset_index()
+            .rename(columns={TimeSeriesDataFrame.ITEMID: self.id_col, TimeSeriesDataFrame.TIMESTAMP: self.time_col})
+        )
 
     def fit_transform(self, df: pd.DataFrame) -> pd.DataFrame:  # type: ignore
         self.ag_scaler = get_target_scaler(name=self.scaler_type, target=self.target_col)