autogluon.timeseries 1.3.2b20250712__py3-none-any.whl → 1.3.2b20250714__py3-none-any.whl

autogluon/timeseries/models/autogluon_tabular/mlforecast.py

@@ -473,7 +473,7 @@ class AbstractMLForecastModel(AbstractTimeSeriesModel):
 
 
 class DirectTabularModel(AbstractMLForecastModel):
-    """Predict all future time series values simultaneously using tabular regression models.
+    """Predict all future time series values simultaneously using a regression model from AutoGluon-Tabular.
 
     A single tabular model is used to forecast all future time series values using the following features:
 
@@ -654,16 +654,16 @@ class DirectTabularModel(AbstractMLForecastModel):
 
 
 class RecursiveTabularModel(AbstractMLForecastModel):
-    """Predict future time series values one by one using TabularPredictor from AutoGluon-Tabular.
+    """Predict future time series values one by one using a regression model from AutoGluon-Tabular.
 
-    A single TabularPredictor is used to forecast the future time series values using the following features:
+    A single tabular regression model is used to forecast the future time series values using the following features:
 
     - lag features (observed time series values) based on ``freq`` of the data
     - time features (e.g., day of the week) based on the timestamp of the measurement
     - known covariates (if available)
     - static features of each item (if available)
 
-    TabularPredictor will always be trained with ``"regression"`` problem type, and dummy quantiles will be
+    The tabular model will always be trained with ``"regression"`` problem type, and dummy quantiles will be
     obtained by assuming that the residuals follow zero-mean normal distribution.
 
     Based on the `mlforecast <https://github.com/Nixtla/mlforecast>`_ library.

autogluon/timeseries/models/autogluon_tabular/per_step.py

@@ -2,15 +2,18 @@ import logging
 import math
 import os
 import time
-from typing import Any, Callable, Dict, List, Optional, Type
+from typing import Any, Callable, Dict, List, 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
@@ -23,8 +26,6 @@ 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,7 +37,11 @@ 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`.
@@ -73,6 +78,8 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
         If None, automatically determined based on available memory to prevent OOM errors.
     """
 
+    _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.
@@ -116,13 +123,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 +145,14 @@ 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)
         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 +173,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 +197,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
 
@@ -313,13 +329,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 +350,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 +391,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],
@@ -382,7 +417,7 @@ class PerStepTabularModel(AbstractTimeSeriesModel):
         """
         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)
         del mlf
@@ -395,6 +430,13 @@ 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(
@@ -425,6 +467,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,

autogluon/timeseries/version.py

@@ -1,4 +1,4 @@
 """This is the autogluon version file."""
 
-__version__ = "1.3.2b20250712"
+__version__ = "1.3.2b20250714"
 __lite__ = False

{autogluon.timeseries-1.3.2b20250712.dist-info → autogluon.timeseries-1.3.2b20250714.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: autogluon.timeseries
-Version: 1.3.2b20250712
+Version: 1.3.2b20250714
 Summary: Fast and Accurate ML in 3 Lines of Code
 Home-page: https://github.com/autogluon/autogluon
 Author: AutoGluon Community
@@ -36,7 +36,7 @@ Requires-Python: >=3.9, <3.13
 Description-Content-Type: text/markdown
 License-File: ../LICENSE
 License-File: ../NOTICE
-Requires-Dist: joblib<2,>=1.1
+Requires-Dist: joblib<1.7,>=1.2
 Requires-Dist: numpy<2.4.0,>=1.25.0
 Requires-Dist: scipy<1.17,>=1.5.4
 Requires-Dist: pandas<2.4.0,>=2.0.0
@@ -55,10 +55,10 @@ 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.3.2b20250712
-Requires-Dist: autogluon.common==1.3.2b20250712
-Requires-Dist: autogluon.features==1.3.2b20250712
-Requires-Dist: autogluon.tabular[catboost,lightgbm,xgboost]==1.3.2b20250712
+Requires-Dist: autogluon.core[raytune]==1.3.2b20250714
+Requires-Dist: autogluon.common==1.3.2b20250714
+Requires-Dist: autogluon.features==1.3.2b20250714
+Requires-Dist: autogluon.tabular[catboost,lightgbm,xgboost]==1.3.2b20250714
 Provides-Extra: all
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"

{autogluon.timeseries-1.3.2b20250712.dist-info → autogluon.timeseries-1.3.2b20250714.dist-info}/RECORD

@@ -1,4 +1,4 @@
-autogluon.timeseries-1.3.2b20250712-py3.9-nspkg.pth,sha256=cQGwpuGPqg1GXscIwt-7PmME1OnSpD-7ixkikJ31WAY,554
+autogluon.timeseries-1.3.2b20250714-py3.9-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=pIn4YSOk0aqCWyBpIlwnAsFnG4h7PLXk8guFH3wFS-w,13923
@@ -6,7 +6,7 @@ autogluon/timeseries/predictor.py,sha256=u4d7-xMs669g5xxqIYuvEyGQ0P6Y8IoToiyg9zU
 autogluon/timeseries/regressor.py,sha256=G0zecniv85wr8EXlXsbiqpKYHE5KeNALHRzPp_hO5qs,12001
 autogluon/timeseries/splitter.py,sha256=yzPca9p2bWV-_VJAptUyyzQsxu-uixAdpMoGQtDzMD4,3205
 autogluon/timeseries/trainer.py,sha256=-xdGZ4v8OTA3AzMjBJ4CwGYhmKBRsY0Q-dm6YioFOmc,57977
-autogluon/timeseries/version.py,sha256=C6OW_vajErF7r9El7B0X_XkhCzzEn70hhuGbhroLKSU,91
+autogluon/timeseries/version.py,sha256=QyavBAXV1tyROK-lM699M991S0GUCC93ub_uqpbzb74,91
 autogluon/timeseries/configs/__init__.py,sha256=BTtHIPCYeGjqgOcvqb8qPD4VNX-ICKOg6wnkew1cPOE,98
 autogluon/timeseries/configs/presets_configs.py,sha256=cLat8ecLlWrI-SC5KLBDCX2SbVXaucemy2pjxJAtSY0,2543
 autogluon/timeseries/dataset/__init__.py,sha256=UvnhAN5tjgxXTHoZMQDy64YMDj4Xxa68yY7NP4vAw0o,81
@@ -23,8 +23,8 @@ autogluon/timeseries/models/abstract/abstract_timeseries_model.py,sha256=cxAZoYe
 autogluon/timeseries/models/abstract/model_trial.py,sha256=ENPg_7nsdxIvaNM0o0UShZ3x8jFlRmwRc5m0fGPC0TM,3720
 autogluon/timeseries/models/abstract/tunable.py,sha256=SFl4vjkb6BfFFaRPVdftnnLYlIyCThutLHxiiAlV6tY,7168
 autogluon/timeseries/models/autogluon_tabular/__init__.py,sha256=E5fZsdFPgVdyCVyj5bGmn_lQFlCMn2NvuRLBMcCFvhM,205
-autogluon/timeseries/models/autogluon_tabular/mlforecast.py,sha256=CBQh23Li__Gmpsv1e5ucMjeBtLFcm2CJbpgqXVNOTNY,37614
-autogluon/timeseries/models/autogluon_tabular/per_step.py,sha256=qCC8ed4pqm6yoW743WJ2z1Nh6WV8-Z8EVqRwX9Lz6eE,20580
+autogluon/timeseries/models/autogluon_tabular/mlforecast.py,sha256=9J95mXR2V_DLXHz0p-VaHA2wi3mF33KggEKMI3YViHM,37641
+autogluon/timeseries/models/autogluon_tabular/per_step.py,sha256=CVdtmVRGn4DYb8AVgqaiycnKrR_KrCkNtwZ8jW-UAGw,22761
 autogluon/timeseries/models/autogluon_tabular/transforms.py,sha256=aI1QJLJaOB5Xy2WA0jo6Jh25MRVyyZ8ONrqlV96kpw0,2735
 autogluon/timeseries/models/autogluon_tabular/utils.py,sha256=Fn3Vu_Q0PCtEUbtNgLp1xIblg7dOdpFlF3W5kLHgruI,63
 autogluon/timeseries/models/chronos/__init__.py,sha256=wT77HzTtmQxW3sw2k0mA5Ot6PSHivX-Uvn5fjM05EU4,60
@@ -61,11 +61,11 @@ autogluon/timeseries/utils/datetime/base.py,sha256=3NdsH3NDq4cVAOSoy3XpaNixyNlbj
 autogluon/timeseries/utils/datetime/lags.py,sha256=dpndFOV-d-AqCTwKeQ5Dz-AfCJTeI27bxDC13QzY4y8,6003
 autogluon/timeseries/utils/datetime/seasonality.py,sha256=YK_2k8hvYIMW-sJPnjGWRtCnvIOthwA2hATB3nwVoD4,834
 autogluon/timeseries/utils/datetime/time_features.py,sha256=MjLi3zQ00uWWJtXH9oGX2GJkTbvjdSiuabSa4kcVuxE,2672
-autogluon.timeseries-1.3.2b20250712.dist-info/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
-autogluon.timeseries-1.3.2b20250712.dist-info/METADATA,sha256=IgR6RZQbUF8j9rMAow5LpeHS1R0EdXQm62mEf1SXkV8,12443
-autogluon.timeseries-1.3.2b20250712.dist-info/NOTICE,sha256=7nPQuj8Kp-uXsU0S5so3-2dNU5EctS5hDXvvzzehd7E,114
-autogluon.timeseries-1.3.2b20250712.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-autogluon.timeseries-1.3.2b20250712.dist-info/namespace_packages.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
-autogluon.timeseries-1.3.2b20250712.dist-info/top_level.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
-autogluon.timeseries-1.3.2b20250712.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-autogluon.timeseries-1.3.2b20250712.dist-info/RECORD,,
+autogluon.timeseries-1.3.2b20250714.dist-info/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
+autogluon.timeseries-1.3.2b20250714.dist-info/METADATA,sha256=GTmk62hA3DVv50k3uxC7vswJlg36ooe0Ikt32dA9z1c,12445
+autogluon.timeseries-1.3.2b20250714.dist-info/NOTICE,sha256=7nPQuj8Kp-uXsU0S5so3-2dNU5EctS5hDXvvzzehd7E,114
+autogluon.timeseries-1.3.2b20250714.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+autogluon.timeseries-1.3.2b20250714.dist-info/namespace_packages.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
+autogluon.timeseries-1.3.2b20250714.dist-info/top_level.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
+autogluon.timeseries-1.3.2b20250714.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+autogluon.timeseries-1.3.2b20250714.dist-info/RECORD,,