autogluon.timeseries 1.2.1b20250423__py3-none-any.whl → 1.2.1b20250424__py3-none-any.whl

autogluon/timeseries/dataset/ts_dataframe.py

@@ -8,11 +8,12 @@ from collections.abc import Iterable
 from itertools import islice
 from pathlib import Path
 from pprint import pformat
-from typing import Any, List, Optional, Tuple, Type, Union
+from typing import TYPE_CHECKING, Any, List, Optional, Tuple, Type, Union
 
 import pandas as pd
 from joblib.parallel import Parallel, delayed
 from pandas.core.internals import ArrayManager, BlockManager  # type: ignore
+from typing_extensions import Self, overload
 
 from autogluon.common.loaders import load_pd
 
@@ -1029,7 +1030,11 @@ class TimeSeriesDataFrame(pd.DataFrame):
 
         # Resampling time for 1 item < overhead time for a single parallel job. Therefore, we group items into chunks
         # so that the speedup from parallelization isn't dominated by the communication costs.
-        chunks = split_into_chunks(pd.DataFrame(self).groupby(level=ITEMID, sort=False), chunk_size)
+        df = pd.DataFrame(self)
+        # Make sure that timestamp index has dtype 'datetime64[ns]', otherwise index may contain NaT values.
+        # See https://github.com/autogluon/autogluon/issues/4917
+        df.index = df.index.set_levels(df.index.levels[1].astype("datetime64[ns]"), level=TIMESTAMP)
+        chunks = split_into_chunks(df.groupby(level=ITEMID, sort=False), chunk_size)
         resampled_chunks = Parallel(n_jobs=num_cpus)(delayed(resample_chunk)(chunk) for chunk in chunks)
         resampled_df = TimeSeriesDataFrame(pd.concat(resampled_chunks))
         resampled_df.static_features = self.static_features
@@ -1038,3 +1043,13 @@ class TimeSeriesDataFrame(pd.DataFrame):
     def to_data_frame(self) -> pd.DataFrame:
         """Convert `TimeSeriesDataFrame` to a `pandas.DataFrame`"""
         return pd.DataFrame(self)
+
+    if TYPE_CHECKING:
+
+        @overload
+        def __new__(cls, data: pd.DataFrame, static_features: Optional[pd.DataFrame] = None) -> Self: ...  # type: ignore
+
+        @overload
+        def __getitem__(self, items: List[str]) -> Self: ...  # type: ignore
+        @overload
+        def __getitem__(self, item: str) -> pd.Series: ...  # type: ignore

autogluon/timeseries/predictor.py

@@ -305,15 +305,32 @@ class TimeSeriesPredictor:
                 df = df.convert_frequency(freq=self.freq)
         return df
 
-    def _check_data_for_evaluation(self, data: TimeSeriesDataFrame, name: str = "data") -> None:
-        """Make sure that provided evaluation data includes both historical and future time series values."""
-        if data.num_timesteps_per_item().min() <= self.prediction_length:
+    def _check_and_prepare_data_frame_for_evaluation(
+        self, data: TimeSeriesDataFrame, cutoff: Optional[int] = None, name: str = "data"
+    ) -> TimeSeriesDataFrame:
+        """
+        Make sure that provided evaluation data includes both historical and future time series values.
+        Slices the dataframe based on cutoff, if needed.
+        """
+        cutoff = -1 * self.prediction_length if cutoff is None else cutoff
+        if not (isinstance(cutoff, int) and cutoff <= -self.prediction_length):
+            raise ValueError(f"`cutoff` should be a negative integer <= -prediction_length, got: {cutoff=}")
+
+        expected_length = -cutoff
+
+        if data.num_timesteps_per_item().min() <= expected_length:
+            var_name = "-cutoff" if expected_length > self.prediction_length else "prediction_length"
             raise ValueError(
-                f"Cannot reserve last prediction_length={self.prediction_length} time steps for evaluation in some "
+                f"Cannot reserve last {expected_length} time steps for evaluation in some "
                 f"time series in {name}. Please make sure that {name} includes both historical and future data, and that"
-                f"all time series have length > prediction_length (at least {self.prediction_length + 1})"
+                f"all time series have length > {var_name} (at least {expected_length + 1})"
             )
 
+        if cutoff < -self.prediction_length:
+            data = data.slice_by_timestep(None, cutoff + self.prediction_length)
+
+        return data
+
     def _get_dataset_stats(self, data: TimeSeriesDataFrame) -> str:
         ts_lengths = data.num_timesteps_per_item()
         median_length = ts_lengths.median()
@@ -701,7 +718,7 @@ class TimeSeriesPredictor:
 
         if tuning_data is not None:
             tuning_data = self._check_and_prepare_data_frame(tuning_data, name="tuning_data")
-            self._check_data_for_evaluation(tuning_data, name="tuning_data")
+            tuning_data = self._check_and_prepare_data_frame_for_evaluation(tuning_data, name="tuning_data")
             logger.info(f"Provided tuning_data has {self._get_dataset_stats(tuning_data)}")
             # TODO: Use num_val_windows to perform multi-window backtests on tuning_data
             if num_val_windows > 0:
@@ -846,6 +863,7 @@ class TimeSeriesPredictor:
         data: Union[TimeSeriesDataFrame, pd.DataFrame, Path, str],
         model: Optional[str] = None,
         metrics: Optional[Union[str, TimeSeriesScorer, List[Union[str, TimeSeriesScorer]]]] = None,
+        cutoff: Optional[int] = None,
         display: bool = False,
         use_cache: bool = True,
     ) -> Dict[str, float]:
@@ -863,11 +881,13 @@ class TimeSeriesPredictor:
         Parameters
         ----------
         data : Union[TimeSeriesDataFrame, pd.DataFrame, Path, str]
-            The data to evaluate the best model on. The last ``prediction_length`` time steps of each time series in
-            ``data`` will be held out for prediction and forecast accuracy will be calculated on these time steps.
+            The data to evaluate the best model on. If a ``cutoff`` is not provided, the last ``prediction_length``
+            time steps of each time series in ``data`` will be held out for prediction and forecast accuracy will
+            be calculated on these time steps. When a ``cutoff`` is provided, the ``-cutoff``-th to the
+            ``-cutoff + prediction_length``-th time steps of each time series are used for evaluation.
 
             Must include both historical and future data (i.e., length of all time series in ``data`` must be at least
-            ``prediction_length + 1``).
+            ``prediction_length + 1``, if ``cutoff`` is not provided, ``-cutoff + 1`` otherwise).
 
             The names and dtypes of columns and static features in ``data`` must match the ``train_data`` used to train
             the predictor.
@@ -880,6 +900,11 @@ class TimeSeriesPredictor:
         metrics : str, TimeSeriesScorer or List[Union[str, TimeSeriesScorer]], optional
             Metric or a list of metrics to compute scores with. Defaults to ``self.eval_metric``. Supports both
             metric names as strings and custom metrics based on TimeSeriesScorer.
+        cutoff : int, optional
+            A *negative* integer less than or equal to ``-1 * prediction_length`` denoting the time step in ``data``
+            where the forecast evaluation starts, i.e., time series are evaluated from the ``-cutoff``-th to the
+            ``-cutoff + prediction_length``-th time step. Defaults to ``-1 * prediction_length``, using the last
+            ``prediction_length`` time steps of each time series for evaluation.
         display : bool, default = False
             If True, the scores will be printed.
         use_cache : bool, default = True
@@ -893,8 +918,10 @@ class TimeSeriesPredictor:
             will have their signs flipped to obey this convention. For example, negative MAPE values will be reported.
             To get the ``eval_metric`` score, do ``output[predictor.eval_metric.name]``.
         """
+
         data = self._check_and_prepare_data_frame(data)
-        self._check_data_for_evaluation(data)
+        data = self._check_and_prepare_data_frame_for_evaluation(data, cutoff=cutoff)
+
         scores_dict = self._learner.evaluate(data, model=model, metrics=metrics, use_cache=use_cache)
         if display:
             logger.info("Evaluations on test data:")
@@ -1010,7 +1037,7 @@ class TimeSeriesPredictor:
         """
         if data is not None:
             data = self._check_and_prepare_data_frame(data)
-            self._check_data_for_evaluation(data)
+            data = self._check_and_prepare_data_frame_for_evaluation(data)
 
         fi_df = self._learner.get_feature_importance(
             data=data,
@@ -1188,6 +1215,7 @@ class TimeSeriesPredictor:
     def leaderboard(
         self,
         data: Optional[Union[TimeSeriesDataFrame, pd.DataFrame, Path, str]] = None,
+        cutoff: Optional[int] = None,
         extra_info: bool = False,
         extra_metrics: Optional[List[Union[str, TimeSeriesScorer]]] = None,
         display: bool = False,
@@ -1216,13 +1244,19 @@ class TimeSeriesPredictor:
         ----------
         data : Union[TimeSeriesDataFrame, pd.DataFrame, Path, str], optional
             dataset used for additional evaluation. Must include both historical and future data (i.e., length of all
-            time series in ``data`` must be at least ``prediction_length + 1``).
+            time series in ``data`` must be at least ``prediction_length + 1``, if ``cutoff`` is not provided,
+            ``-cutoff + 1`` otherwise).
 
             The names and dtypes of columns and static features in ``data`` must match the ``train_data`` used to train
             the predictor.
 
             If provided data is a `pandas.DataFrame`, AutoGluon will attempt to convert it to a `TimeSeriesDataFrame`.
             If a `str` or a `Path` is provided, AutoGluon will attempt to load this file.
+        cutoff : int, optional
+            A *negative* integer less than or equal to ``-1 * prediction_length`` denoting the time step in ``data``
+            where the forecast evaluation starts, i.e., time series are evaluated from the ``-cutoff``-th to the
+            ``-cutoff + prediction_length``-th time step. Defaults to ``-1 * prediction_length``, using the last
+            ``prediction_length`` time steps of each time series for evaluation.
         extra_info : bool, default = False
             If True, the leaderboard will contain an additional column `hyperparameters` with the hyperparameters used
             by each model during training. An empty dictionary `{}` means that the model was trained with default
@@ -1258,10 +1292,12 @@ class TimeSeriesPredictor:
                 raise TypeError(f"TimeSeriesPredictor.leaderboard() got an unexpected keyword argument '{key}'")
         if data is None and extra_metrics is not None:
             raise ValueError("`extra_metrics` is only valid when `data` is specified.")
+        if data is None and cutoff is not None:
+            raise ValueError("`cutoff` is only valid when `data` is specified.")
 
         if data is not None:
             data = self._check_and_prepare_data_frame(data)
-            self._check_data_for_evaluation(data)
+            data = self._check_and_prepare_data_frame_for_evaluation(data, cutoff=cutoff)
 
         leaderboard = self._learner.leaderboard(
             data, extra_info=extra_info, extra_metrics=extra_metrics, use_cache=use_cache
@@ -1430,7 +1466,7 @@ class TimeSeriesPredictor:
             return cast(TimeSeriesDataFrame, ts_df[[self.target]])
 
         test_data = self._check_and_prepare_data_frame(test_data)
-        self._check_data_for_evaluation(test_data, name="test_data")
+        test_data = self._check_and_prepare_data_frame_for_evaluation(test_data, name="test_data")
         test_data = self._learner.feature_generator.transform(test_data)
 
         trainer = self._trainer

autogluon/timeseries/utils/features.py

@@ -398,7 +398,7 @@ class AbstractFeatureImportanceTransform:
         """Transforms a series with the same index as the pandas DataFrame"""
         raise NotImplementedError
 
-    def _transform_series(self, feature_data: pd.Series, is_categorical: bool) -> TimeSeriesDataFrame:
+    def _transform_series(self, feature_data: pd.Series, is_categorical: bool) -> pd.Series:
         """Transforms a series with the same index as the pandas DataFrame"""
         raise NotImplementedError
 
@@ -420,6 +420,7 @@ class AbstractFeatureImportanceTransform:
             with warning_filter():
                 data[feature_name].update(self._transform_series(feature_data, is_categorical=is_categorical))
         elif feature_name in self.covariate_metadata.static_features:
+            assert data.static_features is not None
             feature_data = data.static_features[feature_name].copy()
             feature_data.reset_index(drop=True, inplace=True)
             data.static_features[feature_name] = self._transform_static_series(
@@ -459,6 +460,8 @@ class PermutationFeatureImportanceTransform(AbstractFeatureImportanceTransform):
             )
         elif self.shuffle_type == "naive":
             return pd.Series(feature_data.sample(frac=1, random_state=rng).values, index=feature_data.index)
+        else:
+            raise ValueError(f"Unknown shuffle_type: {self.shuffle_type}")
 
 
 class ConstantReplacementFeatureImportanceTransform(AbstractFeatureImportanceTransform):

autogluon/timeseries/utils/warning_filters.py

@@ -57,7 +57,7 @@ def disable_tqdm():
         from tqdm import tqdm
 
         _init = tqdm.__init__
-        tqdm.__init__ = functools.partialmethod(tqdm.__init__, disable=True)
+        tqdm.__init__ = functools.partialmethod(tqdm.__init__, disable=True)  # type: ignore
         yield
     except ImportError:
         yield

autogluon/timeseries/version.py

@@ -1,4 +1,4 @@
 """This is the autogluon version file."""
 
-__version__ = "1.2.1b20250423"
+__version__ = "1.2.1b20250424"
 __lite__ = False

{autogluon.timeseries-1.2.1b20250423.dist-info → autogluon.timeseries-1.2.1b20250424.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: autogluon.timeseries
-Version: 1.2.1b20250423
+Version: 1.2.1b20250424
 Summary: Fast and Accurate ML in 3 Lines of Code
 Home-page: https://github.com/autogluon/autogluon
 Author: AutoGluon Community
@@ -55,9 +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.2.1b20250423
-Requires-Dist: autogluon.common==1.2.1b20250423
-Requires-Dist: autogluon.tabular[catboost,lightgbm,xgboost]==1.2.1b20250423
+Requires-Dist: autogluon.core[raytune]==1.2.1b20250424
+Requires-Dist: autogluon.common==1.2.1b20250424
+Requires-Dist: autogluon.features==1.2.1b20250424
+Requires-Dist: autogluon.tabular[catboost,lightgbm,xgboost]==1.2.1b20250424
 Provides-Extra: all
 Provides-Extra: chronos-onnx
 Requires-Dist: optimum[onnxruntime]<1.23,>=1.17; extra == "chronos-onnx"

{autogluon.timeseries-1.2.1b20250423.dist-info → autogluon.timeseries-1.2.1b20250424.dist-info}/RECORD

@@ -1,16 +1,16 @@
-autogluon.timeseries-1.2.1b20250423-py3.9-nspkg.pth,sha256=cQGwpuGPqg1GXscIwt-7PmME1OnSpD-7ixkikJ31WAY,554
+autogluon.timeseries-1.2.1b20250424-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=7dqSHKCIX2osjv9cmWWLwaGvdrPvla0HTnsR75bdenY,14112
-autogluon/timeseries/predictor.py,sha256=eklp1Qils6f4vIex8KhLD6nVsUQwZ6Jt9UKkTsSyErM,85739
+autogluon/timeseries/predictor.py,sha256=AIgThzVtqjytEbNZjKM5SdmDJ3PtD-4hyjGBWnI2ot8,88012
 autogluon/timeseries/regressor.py,sha256=xw5VPrXS-NQ_Ts4ppDjoNV0TdqUYjW4VINUtb_BZdiI,11868
 autogluon/timeseries/splitter.py,sha256=yzPca9p2bWV-_VJAptUyyzQsxu-uixAdpMoGQtDzMD4,3205
 autogluon/timeseries/trainer.py,sha256=-8UBCe_uzwOoMk8wHgVEEhN7mN2biumUzGrf5YY6n4w,58131
-autogluon/timeseries/version.py,sha256=5cHaVBGEbXKlEyQMJ8g3TzPJ5O8xRFYaKM8gVl6YgvE,91
+autogluon/timeseries/version.py,sha256=loINeigkP0uoD8mSz8xCUY3ZkGa6XAO4_zkczMDg1so,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
-autogluon/timeseries/dataset/ts_dataframe.py,sha256=uX639T0zD6DDmsO4PbCY_X2gI_4M95Gf4oYCy4etGhk,47169
+autogluon/timeseries/dataset/ts_dataframe.py,sha256=K-rC4pgy-QjPf3WBgpqxTLsxbmJeWb0Su_1C5wiOx3I,47873
 autogluon/timeseries/metrics/__init__.py,sha256=dJCrZ2cHwqhqNctwQjwG-FHgGUmzIFT-D0z72f4RAVM,2104
 autogluon/timeseries/metrics/abstract.py,sha256=CHUZB6xt9oF9yijSOjgGtjLuKo2X0mT6dQDuwg4ZzpU,8192
 autogluon/timeseries/metrics/point.py,sha256=2nlieQcPBCI9hXMT3v0Oe802ykZDuzvEtDpunzt0IVA,15785
@@ -52,19 +52,19 @@ autogluon/timeseries/transforms/__init__.py,sha256=fkFc4Q1Dlh0vVRgO7nPD7BgNL9dOk
 autogluon/timeseries/transforms/covariate_scaler.py,sha256=G56PTHKqCFKiXRKLkLun7mN3-T09jxN-5oI1ISADJdQ,7042
 autogluon/timeseries/transforms/target_scaler.py,sha256=BeT1aP51Wq9EidxC0dVg6dHvampKafpG1uKu4ZaaJPs,6050
 autogluon/timeseries/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-autogluon/timeseries/utils/features.py,sha256=IahkFgY3zzBqldrBtx4WTmxhUTb1CklZQA8RbTOzc48,22527
+autogluon/timeseries/utils/features.py,sha256=7gyRkuD2sMwJivF6O_bW7kADJBnCbBM055CnwkoU94I,22658
 autogluon/timeseries/utils/forecast.py,sha256=vd0Y5YsHU6awu4E7xyDXQGe21P1aB26gwFsA3m09mKw,2197
-autogluon/timeseries/utils/warning_filters.py,sha256=FyXvYW_ylULcZP4R9xNBxojKtvadW3uygXwHK_xHq5g,2522
+autogluon/timeseries/utils/warning_filters.py,sha256=tHvhj9y7c3MP6JrjAedc7UiFFw0_mKYziDQupw8NhiQ,2538
 autogluon/timeseries/utils/datetime/__init__.py,sha256=bTMR8jLh1LW55vHjbOr1zvWRMF_PqbvxpS-cUcNIDWI,173
 autogluon/timeseries/utils/datetime/base.py,sha256=3NdsH3NDq4cVAOSoy3XpaNixyNlbjy4DJ_YYOGuu9x4,1341
 autogluon/timeseries/utils/datetime/lags.py,sha256=gQDk5_zmsY5DUWDUpSaCKYkQ9nHKKY-LsywJQRAoYSk,5988
 autogluon/timeseries/utils/datetime/seasonality.py,sha256=YK_2k8hvYIMW-sJPnjGWRtCnvIOthwA2hATB3nwVoD4,834
 autogluon/timeseries/utils/datetime/time_features.py,sha256=MjLi3zQ00uWWJtXH9oGX2GJkTbvjdSiuabSa4kcVuxE,2672
-autogluon.timeseries-1.2.1b20250423.dist-info/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
-autogluon.timeseries-1.2.1b20250423.dist-info/METADATA,sha256=vs0Qvp4NFtgEq_tw4OkGPvAwv8EPGJWseJ7StCv_cU4,12687
-autogluon.timeseries-1.2.1b20250423.dist-info/NOTICE,sha256=7nPQuj8Kp-uXsU0S5so3-2dNU5EctS5hDXvvzzehd7E,114
-autogluon.timeseries-1.2.1b20250423.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-autogluon.timeseries-1.2.1b20250423.dist-info/namespace_packages.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
-autogluon.timeseries-1.2.1b20250423.dist-info/top_level.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
-autogluon.timeseries-1.2.1b20250423.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-autogluon.timeseries-1.2.1b20250423.dist-info/RECORD,,
+autogluon.timeseries-1.2.1b20250424.dist-info/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
+autogluon.timeseries-1.2.1b20250424.dist-info/METADATA,sha256=UAKQzIEQ7dyWUtNzTZez2aSAa2tvwpMflldTFzY4hOw,12737
+autogluon.timeseries-1.2.1b20250424.dist-info/NOTICE,sha256=7nPQuj8Kp-uXsU0S5so3-2dNU5EctS5hDXvvzzehd7E,114
+autogluon.timeseries-1.2.1b20250424.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+autogluon.timeseries-1.2.1b20250424.dist-info/namespace_packages.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
+autogluon.timeseries-1.2.1b20250424.dist-info/top_level.txt,sha256=giERA4R78OkJf2ijn5slgjURlhRPzfLr7waIcGkzYAo,10
+autogluon.timeseries-1.2.1b20250424.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+autogluon.timeseries-1.2.1b20250424.dist-info/RECORD,,