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

autogluon/timeseries/configs/__init__.py

@@ -1,3 +1,4 @@
-from .presets_configs import TIMESERIES_PRESETS_CONFIGS
+from .hyperparameter_presets import get_hyperparameter_presets
+from .predictor_presets import get_predictor_presets
 
-__all__ = ["TIMESERIES_PRESETS_CONFIGS"]
+__all__ = ["get_hyperparameter_presets", "get_predictor_presets"]

autogluon/timeseries/configs/hyperparameter_presets.py

@@ -0,0 +1,62 @@
+from typing import Any, Union
+
+
+def get_hyperparameter_presets() -> dict[str, dict[str, Union[dict[str, Any], list[dict[str, Any]]]]]:
+    return {
+        "very_light": {
+            "Naive": {},
+            "SeasonalNaive": {},
+            "ETS": {},
+            "Theta": {},
+            "RecursiveTabular": {"max_num_samples": 100_000},
+            "DirectTabular": {"max_num_samples": 100_000},
+        },
+        "light": {
+            "Naive": {},
+            "SeasonalNaive": {},
+            "ETS": {},
+            "Theta": {},
+            "RecursiveTabular": {},
+            "DirectTabular": {},
+            "TemporalFusionTransformer": {},
+            "Chronos": {"model_path": "bolt_small"},
+        },
+        "light_inference": {
+            "SeasonalNaive": {},
+            "DirectTabular": {},
+            "RecursiveTabular": {},
+            "TemporalFusionTransformer": {},
+            "PatchTST": {},
+        },
+        "default": {
+            "SeasonalNaive": {},
+            "AutoETS": {},
+            "NPTS": {},
+            "DynamicOptimizedTheta": {},
+            "RecursiveTabular": {},
+            "DirectTabular": {},
+            "TemporalFusionTransformer": {},
+            "PatchTST": {},
+            "DeepAR": {},
+            "Chronos": [
+                {
+                    "ag_args": {"name_suffix": "ZeroShot"},
+                    "model_path": "bolt_base",
+                },
+                {
+                    "ag_args": {"name_suffix": "FineTuned"},
+                    "model_path": "bolt_small",
+                    "fine_tune": True,
+                    "target_scaler": "standard",
+                    "covariate_regressor": {"model_name": "CAT", "model_hyperparameters": {"iterations": 1_000}},
+                },
+            ],
+            "TiDE": {
+                "encoder_hidden_dim": 256,
+                "decoder_hidden_dim": 256,
+                "temporal_hidden_dim": 64,
+                "num_batches_per_epoch": 100,
+                "lr": 1e-4,
+            },
+        },
+    }

autogluon/timeseries/configs/predictor_presets.py

@@ -0,0 +1,84 @@
+"""Preset configurations for autogluon.timeseries Predictors"""
+
+from typing import Any
+
+from . import get_hyperparameter_presets
+
+TIMESERIES_PRESETS_ALIASES = dict(
+    chronos="chronos_small",
+    best="best_quality",
+    high="high_quality",
+    medium="medium_quality",
+    bq="best_quality",
+    hq="high_quality",
+    mq="medium_quality",
+)
+
+
+def get_predictor_presets() -> dict[str, Any]:
+    hp_presets = get_hyperparameter_presets()
+
+    predictor_presets = dict(
+        best_quality={"hyperparameters": "default", "num_val_windows": 2},
+        high_quality={"hyperparameters": "default"},
+        medium_quality={"hyperparameters": "light"},
+        fast_training={"hyperparameters": "very_light"},
+        # Chronos-Bolt models
+        bolt_tiny={
+            "hyperparameters": {"Chronos": {"model_path": "bolt_tiny"}},
+            "skip_model_selection": True,
+        },
+        bolt_mini={
+            "hyperparameters": {"Chronos": {"model_path": "bolt_mini"}},
+            "skip_model_selection": True,
+        },
+        bolt_small={
+            "hyperparameters": {"Chronos": {"model_path": "bolt_small"}},
+            "skip_model_selection": True,
+        },
+        bolt_base={
+            "hyperparameters": {"Chronos": {"model_path": "bolt_base"}},
+            "skip_model_selection": True,
+        },
+        # Original Chronos models
+        chronos_tiny={
+            "hyperparameters": {"Chronos": {"model_path": "tiny"}},
+            "skip_model_selection": True,
+        },
+        chronos_mini={
+            "hyperparameters": {"Chronos": {"model_path": "mini"}},
+            "skip_model_selection": True,
+        },
+        chronos_small={
+            "hyperparameters": {"Chronos": {"model_path": "small"}},
+            "skip_model_selection": True,
+        },
+        chronos_base={
+            "hyperparameters": {"Chronos": {"model_path": "base"}},
+            "skip_model_selection": True,
+        },
+        chronos_large={
+            "hyperparameters": {"Chronos": {"model_path": "large", "batch_size": 8}},
+            "skip_model_selection": True,
+        },
+        chronos_ensemble={
+            "hyperparameters": {
+                "Chronos": {"model_path": "small"},
+                **hp_presets["light_inference"],
+            }
+        },
+        chronos_large_ensemble={
+            "hyperparameters": {
+                "Chronos": {"model_path": "large", "batch_size": 8},
+                **hp_presets["light_inference"],
+            }
+        },
+    )
+
+    # update with aliases
+    predictor_presets = {
+        **predictor_presets,
+        **{k: predictor_presets[v].copy() for k, v in TIMESERIES_PRESETS_ALIASES.items()},
+    }
+
+    return predictor_presets

autogluon/timeseries/dataset/ts_dataframe.py

@@ -7,7 +7,7 @@ import reprlib
 from collections.abc import Iterable
 from itertools import islice
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, List, Optional, Tuple, Type, Union, overload
+from typing import TYPE_CHECKING, Any, Final, Optional, Type, Union, overload
 
 import numpy as np
 import pandas as pd
@@ -19,11 +19,6 @@ from autogluon.common.loaders import load_pd
 
 logger = logging.getLogger(__name__)
 
-ITEMID = "item_id"
-TIMESTAMP = "timestamp"
-
-IRREGULAR_TIME_INDEX_FREQSTR = "IRREG"
-
 
 class TimeSeriesDataFrame(pd.DataFrame):
     """A collection of univariate time series, where each row is identified by an (``item_id``, ``timestamp``) pair.
@@ -118,9 +113,13 @@ class TimeSeriesDataFrame(pd.DataFrame):
 
     """
 
-    index: pd.MultiIndex
+    index: pd.MultiIndex  # type: ignore
     _metadata = ["_static_features"]
 
+    IRREGULAR_TIME_INDEX_FREQSTR: Final[str] = "IRREG"
+    ITEMID: Final[str] = "item_id"
+    TIMESTAMP: Final[str] = "timestamp"
+
     def __init__(
         self,
         data: Union[pd.DataFrame, str, Path, Iterable],
@@ -175,23 +174,27 @@ class TimeSeriesDataFrame(pd.DataFrame):
         df = df.copy()
         if id_column is not None:
             assert id_column in df.columns, f"Column '{id_column}' not found!"
-            if id_column != ITEMID and ITEMID in df.columns:
-                logger.warning(f"Renaming existing column '{ITEMID}' -> '__{ITEMID}' to avoid name collisions.")
-                df.rename(columns={ITEMID: "__" + ITEMID}, inplace=True)
-            df.rename(columns={id_column: ITEMID}, inplace=True)
+            if id_column != cls.ITEMID and cls.ITEMID in df.columns:
+                logger.warning(
+                    f"Renaming existing column '{cls.ITEMID}' -> '__{cls.ITEMID}' to avoid name collisions."
+                )
+                df.rename(columns={cls.ITEMID: "__" + cls.ITEMID}, inplace=True)
+            df.rename(columns={id_column: cls.ITEMID}, inplace=True)
 
         if timestamp_column is not None:
             assert timestamp_column in df.columns, f"Column '{timestamp_column}' not found!"
-            if timestamp_column != TIMESTAMP and TIMESTAMP in df.columns:
-                logger.warning(f"Renaming existing column '{TIMESTAMP}' -> '__{TIMESTAMP}' to avoid name collisions.")
-                df.rename(columns={TIMESTAMP: "__" + TIMESTAMP}, inplace=True)
-            df.rename(columns={timestamp_column: TIMESTAMP}, inplace=True)
+            if timestamp_column != cls.TIMESTAMP and cls.TIMESTAMP in df.columns:
+                logger.warning(
+                    f"Renaming existing column '{cls.TIMESTAMP}' -> '__{cls.TIMESTAMP}' to avoid name collisions."
+                )
+                df.rename(columns={cls.TIMESTAMP: "__" + cls.TIMESTAMP}, inplace=True)
+            df.rename(columns={timestamp_column: cls.TIMESTAMP}, inplace=True)
 
-        if TIMESTAMP in df.columns:
-            df[TIMESTAMP] = pd.to_datetime(df[TIMESTAMP])
+        if cls.TIMESTAMP in df.columns:
+            df[cls.TIMESTAMP] = pd.to_datetime(df[cls.TIMESTAMP])
 
         cls._validate_data_frame(df)
-        return df.set_index([ITEMID, TIMESTAMP])
+        return df.set_index([cls.ITEMID, cls.TIMESTAMP])
 
     @classmethod
     def _construct_tsdf_from_iterable_dataset(cls, iterable_dataset: Iterable, num_cpus: int = -1) -> pd.DataFrame:
@@ -202,7 +205,7 @@ class TimeSeriesDataFrame(pd.DataFrame):
                 start_timestamp = start_timestamp.to_timestamp(how="S")
             target = ts["target"]
             datetime_index = tuple(pd.date_range(start_timestamp, periods=len(target), freq=freq))
-            idx = pd.MultiIndex.from_product([(item_id,), datetime_index], names=[ITEMID, TIMESTAMP])
+            idx = pd.MultiIndex.from_product([(item_id,), datetime_index], names=[cls.ITEMID, cls.TIMESTAMP])
             return pd.Series(target, name="target", index=idx).to_frame()
 
         cls._validate_iterable(iterable_dataset)
@@ -219,32 +222,34 @@ class TimeSeriesDataFrame(pd.DataFrame):
             raise ValueError(f"data must be a pd.DataFrame, got {type(data)}")
         if not isinstance(data.index, pd.MultiIndex):
             raise ValueError(f"data must have pd.MultiIndex, got {type(data.index)}")
-        if not pd.api.types.is_datetime64_dtype(data.index.dtypes[TIMESTAMP]):
-            raise ValueError(f"for {TIMESTAMP}, the only pandas dtype allowed is `datetime64`.")
-        if not data.index.names == (f"{ITEMID}", f"{TIMESTAMP}"):
-            raise ValueError(f"data must have index names as ('{ITEMID}', '{TIMESTAMP}'), got {data.index.names}")
+        if not pd.api.types.is_datetime64_dtype(data.index.dtypes[cls.TIMESTAMP]):
+            raise ValueError(f"for {cls.TIMESTAMP}, the only pandas dtype allowed is `datetime64`.")
+        if not data.index.names == (f"{cls.ITEMID}", f"{cls.TIMESTAMP}"):
+            raise ValueError(
+                f"data must have index names as ('{cls.ITEMID}', '{cls.TIMESTAMP}'), got {data.index.names}"
+            )
         item_id_index = data.index.levels[0]
         if not (pd.api.types.is_integer_dtype(item_id_index) or pd.api.types.is_string_dtype(item_id_index)):
-            raise ValueError(f"all entries in index `{ITEMID}` must be of integer or string dtype")
+            raise ValueError(f"all entries in index `{cls.ITEMID}` must be of integer or string dtype")
 
     @classmethod
     def _validate_data_frame(cls, df: pd.DataFrame):
         """Validate that a pd.DataFrame with ITEMID and TIMESTAMP columns can be converted to TimeSeriesDataFrame"""
         if not isinstance(df, pd.DataFrame):
             raise ValueError(f"data must be a pd.DataFrame, got {type(df)}")
-        if ITEMID not in df.columns:
-            raise ValueError(f"data must have a `{ITEMID}` column")
-        if TIMESTAMP not in df.columns:
-            raise ValueError(f"data must have a `{TIMESTAMP}` column")
-        if df[ITEMID].isnull().any():
-            raise ValueError(f"`{ITEMID}` column can not have nan")
-        if df[TIMESTAMP].isnull().any():
-            raise ValueError(f"`{TIMESTAMP}` column can not have nan")
-        if not pd.api.types.is_datetime64_dtype(df[TIMESTAMP]):
-            raise ValueError(f"for {TIMESTAMP}, the only pandas dtype allowed is `datetime64`.")
-        item_id_column = df[ITEMID]
+        if cls.ITEMID not in df.columns:
+            raise ValueError(f"data must have a `{cls.ITEMID}` column")
+        if cls.TIMESTAMP not in df.columns:
+            raise ValueError(f"data must have a `{cls.TIMESTAMP}` column")
+        if df[cls.ITEMID].isnull().any():
+            raise ValueError(f"`{cls.ITEMID}` column can not have nan")
+        if df[cls.TIMESTAMP].isnull().any():
+            raise ValueError(f"`{cls.TIMESTAMP}` column can not have nan")
+        if not pd.api.types.is_datetime64_dtype(df[cls.TIMESTAMP]):
+            raise ValueError(f"for {cls.TIMESTAMP}, the only pandas dtype allowed is `datetime64`.")
+        item_id_column = df[cls.ITEMID]
         if not (pd.api.types.is_integer_dtype(item_id_column) or pd.api.types.is_string_dtype(item_id_column)):
-            raise ValueError(f"all entries in column `{ITEMID}` must be of integer or string dtype")
+            raise ValueError(f"all entries in column `{cls.ITEMID}` must be of integer or string dtype")
 
     @classmethod
     def _validate_iterable(cls, data: Iterable):
@@ -386,7 +391,7 @@ class TimeSeriesDataFrame(pd.DataFrame):
     @property
     def item_ids(self) -> pd.Index:
         """List of unique time series IDs contained in the data set."""
-        return self.index.unique(level=ITEMID)
+        return self.index.unique(level=self.ITEMID)
 
     @classmethod
     def _construct_static_features(
@@ -403,10 +408,12 @@ class TimeSeriesDataFrame(pd.DataFrame):
 
         if id_column is not None:
             assert id_column in static_features.columns, f"Column '{id_column}' not found in static_features!"
-            if id_column != ITEMID and ITEMID in static_features.columns:
-                logger.warning(f"Renaming existing column '{ITEMID}' -> '__{ITEMID}' to avoid name collisions.")
-                static_features.rename(columns={ITEMID: "__" + ITEMID}, inplace=True)
-            static_features.rename(columns={id_column: ITEMID}, inplace=True)
+            if id_column != cls.ITEMID and cls.ITEMID in static_features.columns:
+                logger.warning(
+                    f"Renaming existing column '{cls.ITEMID}' -> '__{cls.ITEMID}' to avoid name collisions."
+                )
+                static_features.rename(columns={cls.ITEMID: "__" + cls.ITEMID}, inplace=True)
+            static_features.rename(columns={id_column: cls.ITEMID}, inplace=True)
         return static_features
 
     @property
@@ -431,10 +438,10 @@ class TimeSeriesDataFrame(pd.DataFrame):
 
             # Avoid modifying static features inplace
             value = value.copy()
-            if ITEMID in value.columns and value.index.name != ITEMID:
-                value = value.set_index(ITEMID)
-            if value.index.name != ITEMID:
-                value.index.rename(ITEMID, inplace=True)
+            if self.ITEMID in value.columns and value.index.name != self.ITEMID:
+                value = value.set_index(self.ITEMID)
+            if value.index.name != self.ITEMID:
+                value.index.rename(self.ITEMID, inplace=True)
             missing_item_ids = self.item_ids.difference(value.index)
             if len(missing_item_ids) > 0:
                 raise ValueError(
@@ -456,7 +463,7 @@ class TimeSeriesDataFrame(pd.DataFrame):
             Number of items (individual time series) randomly selected to infer the frequency. Lower values speed up
             the method, but increase the chance that some items with invalid frequency are missed by subsampling.
 
-            If set to `None`, all items will be used for inferring the frequency.
+            If set to ``None``, all items will be used for inferring the frequency.
         raise_if_irregular : bool, default = False
             If True, an exception will be raised if some items have an irregular frequency, or if different items have
             different frequencies.
@@ -467,7 +474,7 @@ class TimeSeriesDataFrame(pd.DataFrame):
             If all time series have a regular frequency, returns a pandas-compatible `frequency alias <https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases>`_.
 
             If some items have an irregular frequency or if different items have different frequencies, returns string
-            `IRREG`.
+            ``IRREG``.
         """
         ts_df = self
         if num_items is not None and ts_df.num_items > num_items:
@@ -514,7 +521,7 @@ class TimeSeriesDataFrame(pd.DataFrame):
                 else:
                     raise ValueError(f"Cannot infer frequency. Multiple frequencies detected: {unique_freqs}")
             else:
-                return IRREGULAR_TIME_INDEX_FREQSTR
+                return self.IRREGULAR_TIME_INDEX_FREQSTR
         else:
             return pd.tseries.frequencies.to_offset(unique_freqs[0]).freqstr
 
@@ -526,7 +533,7 @@ class TimeSeriesDataFrame(pd.DataFrame):
         values. For reliable results, use :meth:`~autogluon.timeseries.TimeSeriesDataFrame.infer_frequency`.
         """
         inferred_freq = self.infer_frequency(num_items=50)
-        return None if inferred_freq == IRREGULAR_TIME_INDEX_FREQSTR else inferred_freq
+        return None if inferred_freq == self.IRREGULAR_TIME_INDEX_FREQSTR else inferred_freq
 
     @property
     def num_items(self):
@@ -536,7 +543,7 @@ class TimeSeriesDataFrame(pd.DataFrame):
     def num_timesteps_per_item(self) -> pd.Series:
         """Number of observations in each time series in the dataframe.
 
-        Returns a `pandas.Series` with item_id as index and number of observations per item as values.
+        Returns a ``pandas.Series`` with ``item_id`` as index and number of observations per item as values.
         """
         counts = pd.Series(self.index.codes[0]).value_counts(sort=False)
         counts.index = self.index.levels[0][counts.index]
@@ -572,7 +579,7 @@ class TimeSeriesDataFrame(pd.DataFrame):
             self.static_features = other._static_features
         return self
 
-    def split_by_time(self, cutoff_time: pd.Timestamp) -> Tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]:
+    def split_by_time(self, cutoff_time: pd.Timestamp) -> tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]:
         """Split dataframe to two different ``TimeSeriesDataFrame`` s before and after a certain ``cutoff_time``.
 
         Parameters
@@ -603,7 +610,7 @@ class TimeSeriesDataFrame(pd.DataFrame):
         This operation is equivalent to selecting a slice ``[start_index : end_index]`` from each time series, and then
         combining these slices into a new ``TimeSeriesDataFrame``. See examples below.
 
-        It is recommended to sort the index with `ts_df.sort_index()` before calling this method to take advantage of
+        It is recommended to sort the index with ``ts_df.sort_index()`` before calling this method to take advantage of
         a fast optimized algorithm.
 
         Parameters
@@ -735,7 +742,7 @@ class TimeSeriesDataFrame(pd.DataFrame):
             return self.loc[mask]
         else:
             # Fall back to a slow groupby operation
-            result = self.groupby(level=ITEMID, sort=False, as_index=False).nth(slice(start_index, end_index))
+            result = self.groupby(level=self.ITEMID, sort=False, as_index=False).nth(slice(start_index, end_index))
             result.static_features = self.static_features
             return result
 
@@ -798,11 +805,11 @@ class TimeSeriesDataFrame(pd.DataFrame):
         method : str, default = "auto"
             Method used to impute missing values.
 
-            - "auto" - first forward fill (to fill the in-between and trailing NaNs), then backward fill (to fill the leading NaNs)
-            - "ffill" or "pad" - propagate last valid observation forward. Note: missing values at the start of the time series are not filled.
-            - "bfill" or "backfill" - use next valid observation to fill gap. Note: this may result in information leakage; missing values at the end of the time series are not filled.
-            - "constant" - replace NaNs with the given constant ``value``.
-            - "interpolate" - fill NaN values using linear interpolation. Note: this may result in information leakage.
+            - ``"auto"`` - first forward fill (to fill the in-between and trailing NaNs), then backward fill (to fill the leading NaNs)
+            - ``"ffill"`` or ``"pad"`` - propagate last valid observation forward. Note: missing values at the start of the time series are not filled.
+            - ``"bfill"`` or ``"backfill"`` - use next valid observation to fill gap. Note: this may result in information leakage; missing values at the end of the time series are not filled.
+            - ``"constant"`` - replace NaNs with the given constant ``value``.
+            - ``"interpolate"`` - fill NaN values using linear interpolation. Note: this may result in information leakage.
         value : float, default = 0.0
             Value used by the "constant" imputation method.
 
@@ -852,12 +859,12 @@ class TimeSeriesDataFrame(pd.DataFrame):
                 "It is highly recommended to call `ts_df.sort_index()` before calling `ts_df.fill_missing_values()`"
             )
 
-        grouped_df = df.groupby(level=ITEMID, sort=False, group_keys=False)
+        grouped_df = df.groupby(level=self.ITEMID, sort=False, group_keys=False)
         if method == "auto":
             filled_df = grouped_df.ffill()
             # If necessary, fill missing values at the start of each time series with bfill
             if filled_df.isna().any(axis=None):
-                filled_df = filled_df.groupby(level=ITEMID, sort=False, group_keys=False).bfill()
+                filled_df = filled_df.groupby(level=self.ITEMID, sort=False, group_keys=False).bfill()
         elif method in ["ffill", "pad"]:
             filled_df = grouped_df.ffill()
         elif method in ["bfill", "backfill"]:
@@ -900,17 +907,17 @@ class TimeSeriesDataFrame(pd.DataFrame):
         return super().sort_index(*args, **kwargs)  # type: ignore
 
     def get_model_inputs_for_scoring(
-        self, prediction_length: int, known_covariates_names: Optional[List[str]] = None
-    ) -> Tuple[TimeSeriesDataFrame, Optional[TimeSeriesDataFrame]]:
+        self, prediction_length: int, known_covariates_names: Optional[list[str]] = None
+    ) -> tuple[TimeSeriesDataFrame, Optional[TimeSeriesDataFrame]]:
         """Prepare model inputs necessary to predict the last ``prediction_length`` time steps of each time series in the dataset.
 
         Parameters
         ----------
         prediction_length : int
             The forecast horizon, i.e., How many time steps into the future must be predicted.
-        known_covariates_names : List[str], optional
+        known_covariates_names : list[str], optional
             Names of the dataframe columns that contain covariates known in the future.
-            See :attr:`known_covariates_names` of :class:`~autogluon.timeseries.TimeSeriesPredictor` for more details.
+            See ``known_covariates_names`` of :class:`~autogluon.timeseries.TimeSeriesPredictor` for more details.
 
         Returns
         -------
@@ -933,7 +940,7 @@ class TimeSeriesDataFrame(pd.DataFrame):
         prediction_length: int,
         end_index: Optional[int] = None,
         suffix: Optional[str] = None,
-    ) -> Tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]:
+    ) -> tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]:
         """Generate a train/test split from the given dataset.
 
         This method can be used to generate splits for multi-window backtesting.
@@ -1083,11 +1090,11 @@ class TimeSeriesDataFrame(pd.DataFrame):
             iterable = iter(iterable)
             return iter(lambda: tuple(islice(iterable, size)), ())
 
-        def resample_chunk(chunk: Iterable[Tuple[str, pd.DataFrame]]) -> pd.DataFrame:
+        def resample_chunk(chunk: Iterable[tuple[str, pd.DataFrame]]) -> pd.DataFrame:
             resampled_dfs = []
             for item_id, df in chunk:
-                resampled_df = df.resample(offset, level=TIMESTAMP, **kwargs).agg(aggregation)
-                resampled_dfs.append(pd.concat({item_id: resampled_df}, names=[ITEMID]))
+                resampled_df = df.resample(offset, level=self.TIMESTAMP, **kwargs).agg(aggregation)
+                resampled_dfs.append(pd.concat({item_id: resampled_df}, names=[self.ITEMID]))
             return pd.concat(resampled_dfs)
 
         # Resampling time for 1 item < overhead time for a single parallel job. Therefore, we group items into chunks
@@ -1095,15 +1102,15 @@ class TimeSeriesDataFrame(pd.DataFrame):
         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)
+        df.index = df.index.set_levels(df.index.levels[1].astype("datetime64[ns]"), level=self.TIMESTAMP)
+        chunks = split_into_chunks(df.groupby(level=self.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
         return resampled_df
 
     def to_data_frame(self) -> pd.DataFrame:
-        """Convert `TimeSeriesDataFrame` to a `pandas.DataFrame`"""
+        """Convert ``TimeSeriesDataFrame`` to a ``pandas.DataFrame``"""
         return pd.DataFrame(self)
 
     def get_indptr(self) -> np.ndarray:
@@ -1124,8 +1131,27 @@ class TimeSeriesDataFrame(pd.DataFrame):
 
         @overload
         def __new__(cls, data: pd.DataFrame, static_features: Optional[pd.DataFrame] = None) -> Self: ...  # type: ignore
+        @overload
+        def __new__(
+            cls,
+            data: Union[pd.DataFrame, str, Path, Iterable],
+            static_features: Optional[Union[pd.DataFrame, str, Path]] = None,
+            id_column: Optional[str] = None,
+            timestamp_column: Optional[str] = None,
+            num_cpus: int = -1,
+            *args,
+            **kwargs,
+        ) -> Self:
+            """This overload is needed since in pandas, during type checking, the default constructor resolves to __new__"""
+            ...
 
         @overload
-        def __getitem__(self, items: List[str]) -> Self: ...  # type: ignore
+        def __getitem__(self, items: list[str]) -> Self: ...  # type: ignore
         @overload
         def __getitem__(self, item: str) -> pd.Series: ...  # type: ignore
+
+
+# TODO: remove with v2.0
+# module-level constants kept for backward compatibility.
+ITEMID = TimeSeriesDataFrame.ITEMID
+TIMESTAMP = TimeSeriesDataFrame.TIMESTAMP

autogluon/timeseries/learner.py

@@ -1,15 +1,14 @@
 import logging
 import reprlib
 import time
-from typing import Any, Dict, List, Literal, Optional, Type, Union
+from typing import Any, Literal, Optional, Type, Union
 
 import pandas as pd
 
 from autogluon.core.learner import AbstractLearner
-from autogluon.timeseries.dataset.ts_dataframe import TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.metrics import TimeSeriesScorer, check_get_evaluation_metric
 from autogluon.timeseries.models.abstract import AbstractTimeSeriesModel
-from autogluon.timeseries.splitter import AbstractWindowSplitter
 from autogluon.timeseries.trainer import TimeSeriesTrainer
 from autogluon.timeseries.utils.features import TimeSeriesFeatureGenerator
 from autogluon.timeseries.utils.forecast import make_future_data_frame
@@ -26,7 +25,7 @@ class TimeSeriesLearner(AbstractLearner):
         self,
         path_context: str,
         target: str = "target",
-        known_covariates_names: Optional[List[str]] = None,
+        known_covariates_names: Optional[list[str]] = None,
         trainer_type: Type[TimeSeriesTrainer] = TimeSeriesTrainer,
         eval_metric: Union[str, TimeSeriesScorer, None] = None,
         prediction_length: int = 1,
@@ -56,11 +55,12 @@ class TimeSeriesLearner(AbstractLearner):
     def fit(
         self,
         train_data: TimeSeriesDataFrame,
-        hyperparameters: Union[str, Dict],
+        hyperparameters: Union[str, dict],
         val_data: Optional[TimeSeriesDataFrame] = None,
         hyperparameter_tune_kwargs: Optional[Union[str, dict]] = None,
         time_limit: Optional[float] = None,
-        val_splitter: Optional[AbstractWindowSplitter] = None,
+        num_val_windows: Optional[int] = None,
+        val_step_size: Optional[int] = None,
         refit_every_n_windows: Optional[int] = 1,
         random_seed: Optional[int] = None,
         **kwargs,
@@ -86,7 +86,8 @@ class TimeSeriesLearner(AbstractLearner):
                 skip_model_selection=kwargs.get("skip_model_selection", False),
                 enable_ensemble=kwargs.get("enable_ensemble", True),
                 covariate_metadata=self.feature_generator.covariate_metadata,
-                val_splitter=val_splitter,
+                num_val_windows=num_val_windows,
+                val_step_size=val_step_size,
                 refit_every_n_windows=refit_every_n_windows,
                 cache_predictions=self.cache_predictions,
                 ensemble_model_type=self.ensemble_model_type,
@@ -194,9 +195,9 @@ class TimeSeriesLearner(AbstractLearner):
         self,
         data: TimeSeriesDataFrame,
         model: Optional[str] = None,
-        metrics: Optional[Union[str, TimeSeriesScorer, List[Union[str, TimeSeriesScorer]]]] = None,
+        metrics: Optional[Union[str, TimeSeriesScorer, list[Union[str, TimeSeriesScorer]]]] = None,
         use_cache: bool = True,
-    ) -> Dict[str, float]:
+    ) -> dict[str, float]:
         data = self.feature_generator.transform(data)
         return self.load_trainer().evaluate(data=data, model=model, metrics=metrics, use_cache=use_cache)
 
@@ -205,7 +206,7 @@ class TimeSeriesLearner(AbstractLearner):
         data: Optional[TimeSeriesDataFrame] = None,
         model: Optional[str] = None,
         metric: Optional[Union[str, TimeSeriesScorer]] = None,
-        features: Optional[List[str]] = None,
+        features: Optional[list[str]] = None,
         time_limit: Optional[float] = None,
         method: Literal["naive", "permutation"] = "permutation",
         subsample_size: int = 50,
@@ -273,7 +274,7 @@ class TimeSeriesLearner(AbstractLearner):
         self,
         data: Optional[TimeSeriesDataFrame] = None,
         extra_info: bool = False,
-        extra_metrics: Optional[List[Union[str, TimeSeriesScorer]]] = None,
+        extra_metrics: Optional[list[Union[str, TimeSeriesScorer]]] = None,
         use_cache: bool = True,
     ) -> pd.DataFrame:
         if data is not None:
@@ -282,7 +283,7 @@ class TimeSeriesLearner(AbstractLearner):
             data, extra_info=extra_info, extra_metrics=extra_metrics, use_cache=use_cache
         )
 
-    def get_info(self, include_model_info: bool = False, **kwargs) -> Dict[str, Any]:
+    def get_info(self, include_model_info: bool = False, **kwargs) -> dict[str, Any]:
         learner_info = super().get_info(include_model_info=include_model_info)
         trainer = self.load_trainer()
         trainer_info = trainer.get_info(include_model_info=include_model_info)
@@ -300,31 +301,31 @@ class TimeSeriesLearner(AbstractLearner):
         return learner_info
 
     def persist_trainer(
-        self, models: Union[Literal["all", "best"], List[str]] = "all", with_ancestors: bool = False
-    ) -> List[str]:
+        self, models: Union[Literal["all", "best"], list[str]] = "all", with_ancestors: bool = False
+    ) -> list[str]:
         """Loads models and trainer in memory so that they don't have to be
         loaded during predictions
 
         Returns
         -------
-        list_of_models : List[str]
+        list_of_models
             List of models persisted in memory
         """
         self.trainer = self.load_trainer()
         return self.trainer.persist(models, with_ancestors=with_ancestors)
 
-    def unpersist_trainer(self) -> List[str]:
+    def unpersist_trainer(self) -> list[str]:
         """Unloads models and trainer from memory. Models will have to be reloaded from disk
         when predicting.
 
         Returns
         -------
-        list_of_models : List[str]
+        list_of_models
             List of models removed from memory
         """
         unpersisted_models = self.load_trainer().unpersist()
         self.trainer = None  # type: ignore
         return unpersisted_models
 
-    def refit_full(self, model: str = "all") -> Dict[str, str]:
+    def refit_full(self, model: str = "all") -> dict[str, str]:
         return self.load_trainer().refit_full(model=model)