autogluon.timeseries 1.4.1b20250907__py3-none-any.whl → 1.4.1b20251215__py3-none-any.whl

autogluon/timeseries/metrics/__init__.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from pprint import pformat
-from typing import Any, Optional, Sequence, Type, Union
+from typing import Any, Sequence, Type
 
 import numpy as np
 
@@ -54,10 +54,10 @@ EXPERIMENTAL_METRICS: dict[str, Type[TimeSeriesScorer]] = {
 
 
 def check_get_evaluation_metric(
-    eval_metric: Union[str, TimeSeriesScorer, Type[TimeSeriesScorer], None],
+    eval_metric: str | TimeSeriesScorer | Type[TimeSeriesScorer] | None,
     prediction_length: int,
-    seasonal_period: Optional[int] = None,
-    horizon_weight: Optional[Sequence[float] | np.ndarray] = None,
+    seasonal_period: int | None = None,
+    horizon_weight: Sequence[float] | np.ndarray | None = None,
 ) -> TimeSeriesScorer:
     """Factory method for TimeSeriesScorer objects.
 

autogluon/timeseries/metrics/abstract.py

@@ -1,5 +1,5 @@
 import warnings
-from typing import Optional, Sequence, Union, overload
+from typing import Sequence, overload
 
 import numpy as np
 import pandas as pd
@@ -52,13 +52,13 @@ class TimeSeriesScorer:
     optimum: float = 0.0
     optimized_by_median: bool = False
     needs_quantile: bool = False
-    equivalent_tabular_regression_metric: Optional[str] = None
+    equivalent_tabular_regression_metric: str | None = None
 
     def __init__(
         self,
         prediction_length: int = 1,
-        seasonal_period: Optional[int] = None,
-        horizon_weight: Optional[Sequence[float]] = None,
+        seasonal_period: int | None = None,
+        horizon_weight: Sequence[float] | None = None,
     ):
         self.prediction_length = int(prediction_length)
         if self.prediction_length < 1:
@@ -192,7 +192,7 @@ class TimeSeriesScorer:
         return self.optimum - self.score(*args, **kwargs)
 
     @staticmethod
-    def _safemean(array: Union[np.ndarray, pd.Series]) -> float:
+    def _safemean(array: np.ndarray | pd.Series) -> float:
         """Compute mean of a numpy array-like object, ignoring inf, -inf and nan values."""
         return float(np.mean(array[np.isfinite(array)]))
 
@@ -240,13 +240,13 @@ class TimeSeriesScorer:
     @overload
     @staticmethod
     def check_get_horizon_weight(
-        horizon_weight: Union[Sequence[float], np.ndarray], prediction_length: int
+        horizon_weight: Sequence[float] | np.ndarray, prediction_length: int
     ) -> np.ndarray: ...
 
     @staticmethod
     def check_get_horizon_weight(
-        horizon_weight: Union[Sequence[float], np.ndarray, None], prediction_length: int
-    ) -> Optional[np.ndarray]:
+        horizon_weight: Sequence[float] | np.ndarray | None, prediction_length: int
+    ) -> np.ndarray | None:
         """Convert horizon_weight to a non-negative numpy array that sums up to prediction_length.
         Raises an exception if horizon_weight has an invalid shape or contains invalid values.
 

autogluon/timeseries/metrics/point.py

@@ -1,6 +1,6 @@
 import logging
 import warnings
-from typing import Optional, Sequence
+from typing import Sequence
 
 import numpy as np
 import pandas as pd
@@ -279,13 +279,13 @@ class MASE(TimeSeriesScorer):
     def __init__(
         self,
         prediction_length: int = 1,
-        seasonal_period: Optional[int] = None,
-        horizon_weight: Optional[Sequence[float]] = None,
+        seasonal_period: int | None = None,
+        horizon_weight: Sequence[float] | None = None,
     ):
         super().__init__(
             prediction_length=prediction_length, seasonal_period=seasonal_period, horizon_weight=horizon_weight
         )
-        self._past_abs_seasonal_error: Optional[pd.Series] = None
+        self._past_abs_seasonal_error: pd.Series | None = None
 
     def save_past_metrics(
         self, data_past: TimeSeriesDataFrame, target: str = "target", seasonal_period: int = 1, **kwargs
@@ -353,13 +353,13 @@ class RMSSE(TimeSeriesScorer):
     def __init__(
         self,
         prediction_length: int = 1,
-        seasonal_period: Optional[int] = None,
-        horizon_weight: Optional[Sequence[float]] = None,
+        seasonal_period: int | None = None,
+        horizon_weight: Sequence[float] | None = None,
     ):
         super().__init__(
             prediction_length=prediction_length, seasonal_period=seasonal_period, horizon_weight=horizon_weight
         )
-        self._past_squared_seasonal_error: Optional[pd.Series] = None
+        self._past_squared_seasonal_error: pd.Series | None = None
 
     def save_past_metrics(
         self, data_past: TimeSeriesDataFrame, target: str = "target", seasonal_period: int = 1, **kwargs
@@ -471,8 +471,8 @@ class WCD(TimeSeriesScorer):
         self,
         alpha: float = 0.5,
         prediction_length: int = 1,
-        seasonal_period: Optional[int] = None,
-        horizon_weight: Optional[Sequence[float]] = None,
+        seasonal_period: int | None = None,
+        horizon_weight: Sequence[float] | None = None,
     ):
         super().__init__(
             prediction_length=prediction_length, seasonal_period=seasonal_period, horizon_weight=horizon_weight

autogluon/timeseries/metrics/quantile.py

@@ -1,9 +1,9 @@
-from typing import Optional, Sequence
+from typing import Sequence
 
 import numpy as np
 import pandas as pd
 
-from autogluon.timeseries.dataset.ts_dataframe import TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 
 from .abstract import TimeSeriesScorer
 from .utils import in_sample_abs_seasonal_error
@@ -92,13 +92,13 @@ class SQL(TimeSeriesScorer):
     def __init__(
         self,
         prediction_length: int = 1,
-        seasonal_period: Optional[int] = None,
-        horizon_weight: Optional[Sequence[float]] = None,
+        seasonal_period: int | None = None,
+        horizon_weight: Sequence[float] | None = None,
     ):
         super().__init__(
             prediction_length=prediction_length, seasonal_period=seasonal_period, horizon_weight=horizon_weight
         )
-        self._past_abs_seasonal_error: Optional[pd.Series] = None
+        self._past_abs_seasonal_error: pd.Series | None = None
 
     def save_past_metrics(
         self, data_past: TimeSeriesDataFrame, target: str = "target", seasonal_period: int = 1, **kwargs

autogluon/timeseries/metrics/utils.py

@@ -1,18 +1,18 @@
 import pandas as pd
 
-from autogluon.timeseries.dataset.ts_dataframe import ITEMID
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 
 
 def _get_seasonal_diffs(*, y_past: pd.Series, seasonal_period: int = 1) -> pd.Series:
-    return y_past.groupby(level=ITEMID, sort=False).diff(seasonal_period).abs()
+    return y_past.groupby(level=TimeSeriesDataFrame.ITEMID, sort=False).diff(seasonal_period).abs()
 
 
 def in_sample_abs_seasonal_error(*, y_past: pd.Series, seasonal_period: int = 1) -> pd.Series:
     """Compute seasonal naive forecast error (predict value from seasonal_period steps ago) for each time series."""
     seasonal_diffs = _get_seasonal_diffs(y_past=y_past, seasonal_period=seasonal_period)
-    return seasonal_diffs.groupby(level=ITEMID, sort=False).mean().fillna(1.0)
+    return seasonal_diffs.groupby(level=TimeSeriesDataFrame.ITEMID, sort=False).mean().fillna(1.0)
 
 
 def in_sample_squared_seasonal_error(*, y_past: pd.Series, seasonal_period: int = 1) -> pd.Series:
     seasonal_diffs = _get_seasonal_diffs(y_past=y_past, seasonal_period=seasonal_period)
-    return seasonal_diffs.pow(2.0).groupby(level=ITEMID, sort=False).mean().fillna(1.0)
+    return seasonal_diffs.pow(2.0).groupby(level=TimeSeriesDataFrame.ITEMID, sort=False).mean().fillna(1.0)

autogluon/timeseries/models/__init__.py

@@ -1,5 +1,5 @@
 from .autogluon_tabular import DirectTabularModel, PerStepTabularModel, RecursiveTabularModel
-from .chronos import ChronosModel
+from .chronos import Chronos2Model, ChronosModel
 from .gluonts import (
     DeepARModel,
     DLinearModel,
@@ -28,6 +28,7 @@ from .local import (
     ZeroModel,
 )
 from .registry import ModelRegistry
+from .toto import TotoModel
 
 __all__ = [
     "ADIDAModel",
@@ -44,6 +45,7 @@ __all__ = [
     "ETSModel",
     "IMAPAModel",
     "ChronosModel",
+    "Chronos2Model",
     "ModelRegistry",
     "NPTSModel",
     "NaiveModel",
@@ -56,6 +58,7 @@ __all__ = [
     "TemporalFusionTransformerModel",
     "ThetaModel",
     "TiDEModel",
+    "TotoModel",
     "WaveNetModel",
     "ZeroModel",
 ]

autogluon/timeseries/models/abstract/abstract_timeseries_model.py

@@ -4,7 +4,7 @@ import os
 import re
 import time
 from abc import ABC, abstractmethod
-from typing import Any, Optional, Sequence, Union
+from typing import Any, Sequence
 
 import pandas as pd
 from typing_extensions import Self
@@ -75,15 +75,15 @@ class TimeSeriesModelBase(ModelBase, ABC):
 
     def __init__(
         self,
-        path: Optional[str] = None,
-        name: Optional[str] = None,
-        hyperparameters: Optional[dict[str, Any]] = None,
-        freq: Optional[str] = None,
+        path: str | None = None,
+        name: str | None = None,
+        hyperparameters: dict[str, Any] | None = None,
+        freq: str | None = None,
         prediction_length: int = 1,
-        covariate_metadata: Optional[CovariateMetadata] = None,
+        covariate_metadata: CovariateMetadata | None = None,
         target: str = "target",
         quantile_levels: Sequence[float] = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9),
-        eval_metric: Union[str, TimeSeriesScorer, None] = None,
+        eval_metric: str | TimeSeriesScorer | None = None,
     ):
         self.name = name or re.sub(r"Model$", "", self.__class__.__name__)
 
@@ -102,7 +102,7 @@ class TimeSeriesModelBase(ModelBase, ABC):
         self.target: str = target
         self.covariate_metadata = covariate_metadata or CovariateMetadata()
 
-        self.freq: Optional[str] = freq
+        self.freq: str | None = freq
         self.prediction_length: int = prediction_length
         self.quantile_levels: list[float] = list(quantile_levels)
 
@@ -117,17 +117,21 @@ class TimeSeriesModelBase(ModelBase, ABC):
         else:
             self.must_drop_median = False
 
-        self._oof_predictions: Optional[list[TimeSeriesDataFrame]] = None
+        self._oof_predictions: list[TimeSeriesDataFrame] | None = None
 
         # user provided hyperparameters and extra arguments that are used during model training
         self._hyperparameters, self._extra_ag_args = self._check_and_split_hyperparameters(hyperparameters)
 
-        self.fit_time: Optional[float] = None  # Time taken to fit in seconds (Training data)
-        self.predict_time: Optional[float] = None  # Time taken to predict in seconds (Validation data)
-        self.predict_1_time: Optional[float] = (
-            None  # Time taken to predict 1 row of data in seconds (with batch size `predict_1_batch_size`)
-        )
-        self.val_score: Optional[float] = None  # Score with eval_metric (Validation data)
+        # Time taken to fit in seconds (Training data)
+        self.fit_time: float | None = None
+        # Time taken to predict in seconds, for a single prediction horizon on validation data
+        self.predict_time: float | None = None
+        # Time taken to predict 1 row of data in seconds (with batch size `predict_1_batch_size`)
+        self.predict_1_time: float | None = None
+        # Useful for ensembles, additional prediction time excluding base models. None for base models.
+        self.predict_time_marginal: float | None = None
+        # Score with eval_metric on validation data
+        self.val_score: float | None = None
 
     def __repr__(self) -> str:
         return self.name
@@ -143,9 +147,14 @@ class TimeSeriesModelBase(ModelBase, ABC):
         self.path = path_context
         self.path_root = self.path.rsplit(self.name, 1)[0]
 
+    def cache_oof_predictions(self, predictions: TimeSeriesDataFrame | list[TimeSeriesDataFrame]) -> None:
+        if isinstance(predictions, TimeSeriesDataFrame):
+            predictions = [predictions]
+        self._oof_predictions = predictions
+
     @classmethod
     def _check_and_split_hyperparameters(
-        cls, hyperparameters: Optional[dict[str, Any]] = None
+        cls, hyperparameters: dict[str, Any] | None = None
     ) -> tuple[dict[str, Any], dict[str, Any]]:
         """Given the user-specified hyperparameters, split into `hyperparameters` and `extra_ag_args`, intended
         to be used during model initialization.
@@ -180,7 +189,7 @@ class TimeSeriesModelBase(ModelBase, ABC):
             )
         return hyperparameters, extra_ag_args
 
-    def save(self, path: Optional[str] = None, verbose: bool = True) -> str:
+    def save(self, path: str | None = None, verbose: bool = True) -> str:
         if path is None:
             path = self.path
 
@@ -242,9 +251,13 @@ class TimeSeriesModelBase(ModelBase, ABC):
         return {}
 
     def get_hyperparameters(self) -> dict:
-        """Get hyperparameters that will be passed to the "inner model" that AutoGluon wraps."""
+        """Get dictionary of hyperparameters that will be passed to the "inner model" that AutoGluon wraps."""
         return {**self._get_default_hyperparameters(), **self._hyperparameters}
 
+    def get_hyperparameter(self, key: str) -> Any:
+        """Get a single hyperparameter value for the "inner model"."""
+        return self.get_hyperparameters()[key]
+
     def get_info(self) -> dict:
         """
         Returns a dictionary of numerous fields describing the model.
@@ -384,15 +397,15 @@ class AbstractTimeSeriesModel(TimeSeriesModelBase, TimeSeriesTunable, metaclass=
 
     def __init__(
         self,
-        path: Optional[str] = None,
-        name: Optional[str] = None,
-        hyperparameters: Optional[dict[str, Any]] = None,
-        freq: Optional[str] = None,
+        path: str | None = None,
+        name: str | None = None,
+        hyperparameters: dict[str, Any] | None = None,
+        freq: str | None = None,
         prediction_length: int = 1,
-        covariate_metadata: Optional[CovariateMetadata] = None,
+        covariate_metadata: CovariateMetadata | None = None,
         target: str = "target",
         quantile_levels: Sequence[float] = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9),
-        eval_metric: Union[str, TimeSeriesScorer, None] = None,
+        eval_metric: str | TimeSeriesScorer | None = None,
     ):
         # TODO: make freq a required argument in AbstractTimeSeriesModel
         super().__init__(
@@ -406,9 +419,9 @@ class AbstractTimeSeriesModel(TimeSeriesModelBase, TimeSeriesTunable, metaclass=
             quantile_levels=quantile_levels,
             eval_metric=eval_metric,
         )
-        self.target_scaler: Optional[TargetScaler]
-        self.covariate_scaler: Optional[CovariateScaler]
-        self.covariate_regressor: Optional[CovariateRegressor]
+        self.target_scaler: TargetScaler | None
+        self.covariate_scaler: CovariateScaler | None
+        self.covariate_regressor: CovariateRegressor | None
 
     def _initialize_transforms_and_regressor(self) -> None:
         self.target_scaler = get_target_scaler(self.get_hyperparameters().get("target_scaler"), target=self.target)
@@ -433,8 +446,8 @@ class AbstractTimeSeriesModel(TimeSeriesModelBase, TimeSeriesTunable, metaclass=
     def fit(
         self,
         train_data: TimeSeriesDataFrame,
-        val_data: Optional[TimeSeriesDataFrame] = None,
-        time_limit: Optional[float] = None,
+        val_data: TimeSeriesDataFrame | None = None,
+        time_limit: float | None = None,
         verbosity: int = 2,
         **kwargs,
     ) -> Self:
@@ -527,10 +540,10 @@ class AbstractTimeSeriesModel(TimeSeriesModelBase, TimeSeriesTunable, metaclass=
     def _fit(
         self,
         train_data: TimeSeriesDataFrame,
-        val_data: Optional[TimeSeriesDataFrame] = None,
-        time_limit: Optional[float] = None,
-        num_cpus: Optional[int] = None,
-        num_gpus: Optional[int] = None,
+        val_data: TimeSeriesDataFrame | None = None,
+        time_limit: float | None = None,
+        num_cpus: int | None = None,
+        num_gpus: int | None = None,
         verbosity: int = 2,
         **kwargs,
     ) -> None:
@@ -551,7 +564,7 @@ class AbstractTimeSeriesModel(TimeSeriesModelBase, TimeSeriesTunable, metaclass=
                 "as hyperparameters when initializing or use `hyperparameter_tune` instead."
             )
 
-    def _log_unused_hyperparameters(self, extra_allowed_hyperparameters: Optional[list[str]] = None) -> None:
+    def _log_unused_hyperparameters(self, extra_allowed_hyperparameters: list[str] | None = None) -> None:
         """Log a warning if unused hyperparameters were provided to the model."""
         allowed_hyperparameters = self.allowed_hyperparameters
         if extra_allowed_hyperparameters is not None:
@@ -567,7 +580,7 @@ class AbstractTimeSeriesModel(TimeSeriesModelBase, TimeSeriesTunable, metaclass=
     def predict(
         self,
         data: TimeSeriesDataFrame,
-        known_covariates: Optional[TimeSeriesDataFrame] = None,
+        known_covariates: TimeSeriesDataFrame | None = None,
         **kwargs,
     ) -> TimeSeriesDataFrame:
         """Given a dataset, predict the next `self.prediction_length` time steps.
@@ -648,7 +661,7 @@ class AbstractTimeSeriesModel(TimeSeriesModelBase, TimeSeriesTunable, metaclass=
     def _predict(
         self,
         data: TimeSeriesDataFrame,
-        known_covariates: Optional[TimeSeriesDataFrame] = None,
+        known_covariates: TimeSeriesDataFrame | None = None,
         **kwargs,
     ) -> TimeSeriesDataFrame:
         """Private method for `predict`. See `predict` for documentation of arguments."""
@@ -731,7 +744,7 @@ class AbstractTimeSeriesModel(TimeSeriesModelBase, TimeSeriesTunable, metaclass=
         )
         predict_start_time = time.time()
         oof_predictions = self.predict(past_data, known_covariates=known_covariates, **predict_kwargs)
-        self._oof_predictions = [oof_predictions]
+        self.cache_oof_predictions(oof_predictions)
         if store_predict_time:
             self.predict_time = time.time() - predict_start_time
         if store_val_score:
@@ -740,9 +753,9 @@ class AbstractTimeSeriesModel(TimeSeriesModelBase, TimeSeriesTunable, metaclass=
     def preprocess(
         self,
         data: TimeSeriesDataFrame,
-        known_covariates: Optional[TimeSeriesDataFrame] = None,
+        known_covariates: TimeSeriesDataFrame | None = None,
         is_train: bool = False,
         **kwargs,
-    ) -> tuple[TimeSeriesDataFrame, Optional[TimeSeriesDataFrame]]:
+    ) -> tuple[TimeSeriesDataFrame, TimeSeriesDataFrame | None]:
         """Method that implements model-specific preprocessing logic."""
         return data, known_covariates

autogluon/timeseries/models/abstract/model_trial.py

@@ -76,7 +76,8 @@ def fit_and_save_model(model, fit_kwargs, train_data, val_data, eval_metric, tim
     time_fit_start = time.time()
     model.fit(train_data=train_data, val_data=val_data, time_limit=time_left, **fit_kwargs)
     model.fit_time = time.time() - time_fit_start
-    model.score_and_cache_oof(val_data, store_val_score=True, store_predict_time=True)
+    if val_data is not None:
+        model.score_and_cache_oof(val_data, store_val_score=True, store_predict_time=True)
 
     logger.debug(f"\tHyperparameter tune run: {model.name}")
     logger.debug(f"\t\t{model.val_score:<7.4f}".ljust(15) + f"= Validation score ({eval_metric.name_with_sign})")

autogluon/timeseries/models/abstract/tunable.py

@@ -5,7 +5,7 @@ import os
 import time
 from abc import ABC, abstractmethod
 from contextlib import nullcontext
-from typing import Any, Optional, Union
+from typing import Any
 
 from typing_extensions import Self
 
@@ -37,12 +37,12 @@ class TimeSeriesTunable(Tunable, ABC):
     def hyperparameter_tune(
         self,
         train_data: TimeSeriesDataFrame,
-        val_data: Optional[TimeSeriesDataFrame],
+        val_data: TimeSeriesDataFrame | None,
         val_splitter: Any = None,
-        default_num_trials: Optional[int] = 1,
-        refit_every_n_windows: Optional[int] = 1,
-        hyperparameter_tune_kwargs: Union[str, dict] = "auto",
-        time_limit: Optional[float] = None,
+        default_num_trials: int | None = 1,
+        refit_every_n_windows: int | None = 1,
+        hyperparameter_tune_kwargs: str | dict = "auto",
+        time_limit: float | None = None,
     ) -> tuple[dict[str, Any], Any]:
         hpo_executor = self._get_default_hpo_executor()
         hpo_executor.initialize(
@@ -144,13 +144,13 @@ class TimeSeriesTunable(Tunable, ABC):
         """
         return None
 
-    def get_minimum_resources(self, is_gpu_available: bool = False) -> dict[str, Union[int, float]]:
+    def get_minimum_resources(self, is_gpu_available: bool = False) -> dict[str, int | float]:
         return {
             "num_cpus": 1,
         }
 
     def _save_with_data(
-        self, train_data: TimeSeriesDataFrame, val_data: Optional[TimeSeriesDataFrame]
+        self, train_data: TimeSeriesDataFrame, val_data: TimeSeriesDataFrame | None
     ) -> tuple[str, str]:
         self.path = os.path.abspath(self.path)
         self.path_root = self.path.rsplit(self.name, 1)[0]