autogluon.timeseries 1.2.1b20250224__py3-none-any.whl → 1.4.1b20251215__py3-none-any.whl

autogluon/timeseries/trainer/utils.py

@@ -0,0 +1,17 @@
+import logging
+
+logger = logging.getLogger("autogluon.timeseries.trainer")
+
+
+def log_scores_and_times(
+    val_score: float | None,
+    fit_time: float | None,
+    predict_time: float | None,
+    eval_metric_name: str,
+):
+    if val_score is not None:
+        logger.info(f"\t{val_score:<7.4f}".ljust(15) + f"= Validation score ({eval_metric_name})")
+    if fit_time is not None:
+        logger.info(f"\t{fit_time:<7.2f} s".ljust(15) + "= Training runtime")
+    if predict_time is not None:
+        logger.info(f"\t{predict_time:<7.2f} s".ljust(15) + "= Validation (prediction) runtime")

autogluon/timeseries/transforms/__init__.py

@@ -1,13 +1,2 @@
-from .covariate_scaler import (
-    CovariateScaler,
-    GlobalCovariateScaler,
-    get_covariate_scaler_from_name,
-)
-from .target_scaler import (
-    LocalStandardScaler,
-    LocalMinMaxScaler,
-    LocalMeanAbsScaler,
-    LocalRobustScaler,
-    LocalTargetScaler,
-    get_target_scaler_from_name
-)
+from .covariate_scaler import CovariateScaler, get_covariate_scaler
+from .target_scaler import TargetScaler, get_target_scaler

autogluon/timeseries/transforms/covariate_scaler.py

@@ -1,47 +1,32 @@
 import logging
-from typing import Dict, List, Literal, Optional
+from typing import Literal, Protocol, overload, runtime_checkable
 
 import numpy as np
 import pandas as pd
 from sklearn.compose import ColumnTransformer
 from sklearn.preprocessing import QuantileTransformer, StandardScaler
 
-from autogluon.timeseries.dataset.ts_dataframe import TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.utils.features import CovariateMetadata
 from autogluon.timeseries.utils.warning_filters import warning_filter
 
 logger = logging.getLogger(__name__)
 
 
-class CovariateScaler:
+@runtime_checkable
+class CovariateScaler(Protocol):
     """Apply scaling to covariates and static features.
 
     This can be helpful for deep learning models that assume that the inputs are normalized.
     """
 
-    def __init__(
-        self,
-        metadata: CovariateMetadata,
-        use_known_covariates: bool = True,
-        use_past_covariates: bool = True,
-        use_static_features: bool = True,
-        **kwargs,
-    ):
-        self.metadata = metadata
-        self.use_known_covariates = use_known_covariates
-        self.use_past_covariates = use_past_covariates
-        self.use_static_features = use_static_features
-
-    def fit_transform(self, data: TimeSeriesDataFrame) -> TimeSeriesDataFrame:
-        raise NotImplementedError
+    def fit_transform(self, data: TimeSeriesDataFrame) -> TimeSeriesDataFrame: ...
 
-    def transform(self, data: TimeSeriesDataFrame) -> TimeSeriesDataFrame:
-        raise NotImplementedError
+    def transform(self, data: TimeSeriesDataFrame) -> TimeSeriesDataFrame: ...
 
     def transform_known_covariates(
-        self, known_covariates: Optional[TimeSeriesDataFrame] = None
-    ) -> Optional[TimeSeriesDataFrame]:
-        raise NotImplementedError
+        self, known_covariates: TimeSeriesDataFrame | None = None
+    ) -> TimeSeriesDataFrame | None: ...
 
 
 class GlobalCovariateScaler(CovariateScaler):
@@ -57,15 +42,18 @@ class GlobalCovariateScaler(CovariateScaler):
 
     def __init__(
         self,
-        metadata: CovariateMetadata,
+        covariate_metadata: CovariateMetadata,
         use_known_covariates: bool = True,
         use_past_covariates: bool = True,
         use_static_features: bool = True,
         skew_threshold: float = 0.99,
     ):
-        super().__init__(metadata, use_known_covariates, use_past_covariates, use_static_features)
+        self.covariate_metadata = covariate_metadata
+        self.use_known_covariates = use_known_covariates
+        self.use_past_covariates = use_past_covariates
+        self.use_static_features = use_static_features
         self.skew_threshold = skew_threshold
-        self._column_transformers: Optional[Dict[Literal["known", "past", "static"], ColumnTransformer]] = None
+        self._column_transformers: dict[Literal["known", "past", "static"], ColumnTransformer] | None = None
 
     def is_fit(self) -> bool:
         return self._column_transformers is not None
@@ -73,18 +61,18 @@ class GlobalCovariateScaler(CovariateScaler):
     def fit(self, data: TimeSeriesDataFrame) -> "GlobalCovariateScaler":
         self._column_transformers = {}
 
-        if self.use_known_covariates and len(self.metadata.known_covariates_real) > 0:
+        if self.use_known_covariates and len(self.covariate_metadata.known_covariates_real) > 0:
             self._column_transformers["known"] = self._get_transformer_for_columns(
-                data, columns=self.metadata.known_covariates_real
+                data, columns=self.covariate_metadata.known_covariates_real
             )
-        if self.use_past_covariates and len(self.metadata.past_covariates_real) > 0:
+        if self.use_past_covariates and len(self.covariate_metadata.past_covariates_real) > 0:
             self._column_transformers["past"] = self._get_transformer_for_columns(
-                data, columns=self.metadata.past_covariates_real
+                data, columns=self.covariate_metadata.past_covariates_real
             )
-        if self.use_static_features and len(self.metadata.static_features_real) > 0:
+        if self.use_static_features and len(self.covariate_metadata.static_features_real) > 0:
             assert data.static_features is not None
             self._column_transformers["static"] = self._get_transformer_for_columns(
-                data.static_features, columns=self.metadata.static_features_real
+                data.static_features, columns=self.covariate_metadata.static_features_real
             )
 
         return self
@@ -100,15 +88,15 @@ class GlobalCovariateScaler(CovariateScaler):
         assert self._column_transformers is not None, "CovariateScaler must be fit before transform can be called"
 
         if "known" in self._column_transformers:
-            columns = self.metadata.known_covariates_real
+            columns = self.covariate_metadata.known_covariates_real
             data[columns] = self._column_transformers["known"].transform(data[columns])
 
         if "past" in self._column_transformers:
-            columns = self.metadata.past_covariates_real
+            columns = self.covariate_metadata.past_covariates_real
             data[columns] = self._column_transformers["past"].transform(data[columns])
 
         if "static" in self._column_transformers:
-            columns = self.metadata.static_features_real
+            columns = self.covariate_metadata.static_features_real
             assert data.static_features is not None
 
             data.static_features[columns] = self._column_transformers["static"].transform(
@@ -117,19 +105,19 @@ class GlobalCovariateScaler(CovariateScaler):
         return data
 
     def transform_known_covariates(
-        self, known_covariates: Optional[TimeSeriesDataFrame] = None
-    ) -> Optional[TimeSeriesDataFrame]:
+        self, known_covariates: TimeSeriesDataFrame | None = None
+    ) -> TimeSeriesDataFrame | None:
         assert self._column_transformers is not None, "CovariateScaler must be fit before transform can be called"
 
         if "known" in self._column_transformers:
-            columns = self.metadata.known_covariates_real
+            columns = self.covariate_metadata.known_covariates_real
             assert known_covariates is not None
 
             known_covariates = known_covariates.copy()
             known_covariates[columns] = self._column_transformers["known"].transform(known_covariates[columns])
         return known_covariates
 
-    def _get_transformer_for_columns(self, df: pd.DataFrame, columns: List[str]) -> ColumnTransformer:
+    def _get_transformer_for_columns(self, df: pd.DataFrame, columns: list[str]) -> ColumnTransformer:
         """Passthrough bool features, use QuantileTransform for skewed features, and use StandardScaler for the rest.
 
         The preprocessing logic is similar to the TORCH_NN model from Tabular.
@@ -162,7 +150,13 @@ AVAILABLE_COVARIATE_SCALERS = {
 }
 
 
-def get_covariate_scaler_from_name(name: Literal["global"], **scaler_kwargs) -> CovariateScaler:
+@overload
+def get_covariate_scaler(name: None, **scaler_kwargs) -> None: ...
+@overload
+def get_covariate_scaler(name: Literal["global"], **scaler_kwargs) -> GlobalCovariateScaler: ...
+def get_covariate_scaler(name: Literal["global"] | None = None, **scaler_kwargs) -> CovariateScaler | None:
+    if name is None:
+        return None
     if name not in AVAILABLE_COVARIATE_SCALERS:
         raise KeyError(
             f"Covariate scaler type {name} not supported. Available scalers: {list(AVAILABLE_COVARIATE_SCALERS)}"

autogluon/timeseries/transforms/target_scaler.py

@@ -1,12 +1,23 @@
-from typing import Literal, Optional, Tuple, Union
+from typing import Literal, Protocol, overload
 
 import numpy as np
 import pandas as pd
+from typing_extensions import Self
 
-from autogluon.timeseries.dataset.ts_dataframe import ITEMID, TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 
 
-class LocalTargetScaler:
+class TargetScaler(Protocol):
+    def fit_transform(self, data: TimeSeriesDataFrame) -> TimeSeriesDataFrame: ...
+
+    def fit(self, data: TimeSeriesDataFrame) -> Self: ...
+
+    def transform(self, data: TimeSeriesDataFrame) -> TimeSeriesDataFrame: ...
+
+    def inverse_transform(self, predictions: TimeSeriesDataFrame) -> TimeSeriesDataFrame: ...
+
+
+class LocalTargetScaler(TargetScaler):
     """Applies an affine transformation (x - loc) / scale independently to each time series in the dataset."""
 
     def __init__(
@@ -16,10 +27,10 @@ class LocalTargetScaler:
     ):
         self.target = target
         self.min_scale = min_scale
-        self.loc: Optional[pd.Series] = None
-        self.scale: Optional[pd.Series] = None
+        self.loc: pd.Series | None = None
+        self.scale: pd.Series | None = None
 
-    def _compute_loc_scale(self, target_series: pd.Series) -> Tuple[Optional[pd.Series], Optional[pd.Series]]:
+    def _compute_loc_scale(self, target_series: pd.Series) -> tuple[pd.Series | None, pd.Series | None]:
         raise NotImplementedError
 
     def fit_transform(self, data: TimeSeriesDataFrame) -> TimeSeriesDataFrame:
@@ -34,7 +45,7 @@ class LocalTargetScaler:
             self.scale = self.scale.clip(lower=self.min_scale).replace([np.inf, -np.inf], np.nan).fillna(1.0)
         return self
 
-    def _reindex_loc_scale(self, item_index: pd.Index) -> Tuple[Union[np.ndarray, float], Union[np.ndarray, float]]:
+    def _reindex_loc_scale(self, item_index: pd.Index) -> tuple[np.ndarray | float, np.ndarray | float]:
         """Reindex loc and scale parameters for the given item_ids and convert them to an array-like."""
         if self.loc is not None:
             loc = self.loc.reindex(item_index).to_numpy()
@@ -48,12 +59,12 @@ class LocalTargetScaler:
 
     def transform(self, data: TimeSeriesDataFrame) -> TimeSeriesDataFrame:
         """Apply scaling to the target column in the dataframe."""
-        loc, scale = self._reindex_loc_scale(item_index=data.index.get_level_values(ITEMID))
+        loc, scale = self._reindex_loc_scale(item_index=data.index.get_level_values(TimeSeriesDataFrame.ITEMID))
         return data.assign(**{self.target: (data[self.target] - loc) / scale})
 
     def inverse_transform(self, predictions: TimeSeriesDataFrame) -> TimeSeriesDataFrame:
         """Apply inverse scaling to all columns in the predictions dataframe."""
-        loc, scale = self._reindex_loc_scale(item_index=predictions.index.get_level_values(ITEMID))
+        loc, scale = self._reindex_loc_scale(item_index=predictions.index.get_level_values(TimeSeriesDataFrame.ITEMID))
         return predictions.assign(**{col: predictions[col] * scale + loc for col in predictions.columns})
 
 
@@ -63,16 +74,16 @@ class LocalStandardScaler(LocalTargetScaler):
     The resulting affine transformation is (x - loc) / scale, where scale = std(x), loc = mean(x).
     """
 
-    def _compute_loc_scale(self, target_series: pd.Series) -> Tuple[pd.Series, pd.Series]:
-        stats = target_series.groupby(level=ITEMID, sort=False).agg(["mean", "std"])
+    def _compute_loc_scale(self, target_series: pd.Series) -> tuple[pd.Series, pd.Series]:
+        stats = target_series.groupby(level=TimeSeriesDataFrame.ITEMID, sort=False).agg(["mean", "std"])
         return stats["mean"], stats["std"]
 
 
 class LocalMeanAbsScaler(LocalTargetScaler):
     """Applies mean absolute scaling to each time series in the dataset."""
 
-    def _compute_loc_scale(self, target_series: pd.Series) -> Tuple[Optional[pd.Series], pd.Series]:
-        scale = target_series.abs().groupby(level=ITEMID, sort=False).agg("mean")
+    def _compute_loc_scale(self, target_series: pd.Series) -> tuple[pd.Series | None, pd.Series]:
+        scale = target_series.abs().groupby(level=TimeSeriesDataFrame.ITEMID, sort=False).agg("mean")
         return None, scale
 
 
@@ -82,8 +93,8 @@ class LocalMinMaxScaler(LocalTargetScaler):
     The resulting affine transformation is (x - loc) / scale, where scale = max(x) - min(x), loc = min(x) / scale.
     """
 
-    def _compute_loc_scale(self, target_series: pd.Series) -> Tuple[pd.Series, pd.Series]:
-        stats = target_series.abs().groupby(level=ITEMID, sort=False).agg(["min", "max"])
+    def _compute_loc_scale(self, target_series: pd.Series) -> tuple[pd.Series, pd.Series]:
+        stats = target_series.abs().groupby(level=TimeSeriesDataFrame.ITEMID, sort=False).agg(["min", "max"])
         scale = (stats["max"] - stats["min"]).clip(lower=self.min_scale)
         loc = stats["min"]
         return loc, scale
@@ -106,8 +117,8 @@ class LocalRobustScaler(LocalTargetScaler):
         self.q_max = 0.75
         assert 0 < self.q_min < self.q_max < 1
 
-    def _compute_loc_scale(self, target_series: pd.Series) -> Tuple[pd.Series, pd.Series]:
-        grouped = target_series.groupby(level=ITEMID, sort=False)
+    def _compute_loc_scale(self, target_series: pd.Series) -> tuple[pd.Series, pd.Series]:
+        grouped = target_series.groupby(level=TimeSeriesDataFrame.ITEMID, sort=False)
         loc = grouped.median()
         lower = grouped.quantile(self.q_min)
         upper = grouped.quantile(self.q_max)
@@ -123,10 +134,16 @@ AVAILABLE_TARGET_SCALERS = {
 }
 
 
-def get_target_scaler_from_name(
-    name: Literal["standard", "mean_abs", "min_max", "robust"], **scaler_kwargs
-) -> LocalTargetScaler:
+@overload
+def get_target_scaler(name: None, **scaler_kwargs) -> None: ...
+@overload
+def get_target_scaler(name: Literal["standard", "mean_abs", "min_max", "robust"], **scaler_kwargs) -> TargetScaler: ...
+def get_target_scaler(
+    name: Literal["standard", "mean_abs", "min_max", "robust"] | None, **scaler_kwargs
+) -> TargetScaler | None:
     """Get LocalTargetScaler object from a string."""
+    if name is None:
+        return None
     if name not in AVAILABLE_TARGET_SCALERS:
         raise KeyError(f"Scaler type {name} not supported. Available scalers: {list(AVAILABLE_TARGET_SCALERS)}")
     return AVAILABLE_TARGET_SCALERS[name](**scaler_kwargs)

autogluon/timeseries/utils/constants.py

@@ -0,0 +1,10 @@
+import joblib.externals.loky
+from joblib import cpu_count
+
+# By default, joblib w/ loky backend kills processes that take >300MB of RAM assuming that this is caused by a memory
+# leak. This leads to problems for some memory-hungry models like AutoARIMA/Theta.
+# This monkey patch removes this undesired behavior
+joblib.externals.loky.process_executor._MAX_MEMORY_LEAK_SIZE = int(3e10)
+
+# We use the same default n_jobs across AG-TS to ensure that Joblib reuses the process pool
+AG_DEFAULT_N_JOBS = max(cpu_count(only_physical_cores=True), 1)

autogluon/timeseries/utils/datetime/lags.py

@@ -2,8 +2,6 @@
 Generate lag indices based on frequency string. Adapted from gluonts.time_feature.lag.
 """
 
-from typing import List, Optional
-
 import numpy as np
 import pandas as pd
 
@@ -70,9 +68,9 @@ def _make_lags_for_semi_month(multiple, num_cycles=3):
 def get_lags_for_frequency(
     freq: str,
     lag_ub: int = 1200,
-    num_lags: Optional[int] = None,
+    num_lags: int | None = None,
     num_default_lags: int = 7,
-) -> List[int]:
+) -> list[int]:
     """
     Generates a list of lags that that are appropriate for the given frequency
     string.
@@ -164,7 +162,7 @@ def get_lags_for_frequency(
         raise Exception(f"Cannot get lags for unsupported frequency {freq}")
 
     # flatten lags list and filter
-    lags = [int(lag) for sub_list in lags for lag in sub_list if 7 < lag <= lag_ub]
+    lags = [int(lag) for sub_list in lags for lag in sub_list if num_default_lags < lag <= lag_ub]
     lags = list(range(1, num_default_lags + 1)) + sorted(list(set(lags)))
 
     return sorted(set(lags))[:num_lags]

autogluon/timeseries/utils/datetime/seasonality.py

@@ -1,5 +1,3 @@
-from typing import Union
-
 import pandas as pd
 
 from .base import norm_freq_str
@@ -22,7 +20,7 @@ DEFAULT_SEASONALITIES = {
 }
 
 
-def get_seasonality(freq: Union[str, None]) -> int:
+def get_seasonality(freq: str | None) -> int:
     """Return the seasonality of a given frequency. Adapted from ``gluonts.time_feature.seasonality``."""
     if freq is None:
         return 1

autogluon/timeseries/utils/datetime/time_features.py

@@ -2,7 +2,7 @@
 Generate time features based on frequency string. Adapted from gluonts.time_feature.time_feature.
 """
 
-from typing import Callable, List
+from typing import Callable
 
 import numpy as np
 import pandas as pd
@@ -56,7 +56,7 @@ def second_of_minute(index: pd.DatetimeIndex) -> np.ndarray:
     return _normalize(index.second, num=60)
 
 
-def get_time_features_for_frequency(freq) -> List[Callable]:
+def get_time_features_for_frequency(freq) -> list[Callable]:
     features_by_offset_name = {
         "YE": [],
         "QE": [quarter_of_year],