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

autogluon/timeseries/regressor.py

@@ -1,76 +1,93 @@
 import logging
 import time
-from typing import Any, Dict, Optional
+from typing import Any, Protocol, overload, runtime_checkable
 
 import numpy as np
 import pandas as pd
 
 from autogluon.core.models import AbstractModel
-from autogluon.tabular.trainer.model_presets.presets import MODEL_TYPES as TABULAR_MODEL_TYPES
-from autogluon.timeseries.dataset.ts_dataframe import ITEMID, TimeSeriesDataFrame
+from autogluon.tabular.registry import ag_model_registry as tabular_ag_model_registry
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.utils.features import CovariateMetadata
 
 logger = logging.getLogger(__name__)
 
 
-class CovariateRegressor:
+@runtime_checkable
+class CovariateRegressor(Protocol):
+    def is_fit(self) -> bool: ...
+
+    def fit(self, data: TimeSeriesDataFrame, time_limit: float | None = None, **kwargs) -> "CovariateRegressor": ...
+
+    def transform(self, data: TimeSeriesDataFrame) -> TimeSeriesDataFrame: ...
+
+    def fit_transform(
+        self, data: TimeSeriesDataFrame, time_limit: float | None = None, **kwargs
+    ) -> TimeSeriesDataFrame: ...
+
+    def inverse_transform(
+        self,
+        predictions: TimeSeriesDataFrame,
+        known_covariates: TimeSeriesDataFrame,
+        static_features: pd.DataFrame | None,
+    ) -> TimeSeriesDataFrame: ...
+
+
+class GlobalCovariateRegressor(CovariateRegressor):
     """Predicts target values from the covariates for the same observation.
 
     The model construct the feature matrix using known_covariates and static_features.
 
     Parameters
     ----------
-    model_name : str
-        Name of the tabular regression model. See `autogluon.tabular.trainer.model_presets.presets.MODEL_TYPES` for the
-        list of available models.
-    model_hyperparameters : dict or None
+    model_name
+        Name of the tabular regression model. See ``autogluon.tabular.registry.ag_model_registry`` or
+        `the documentation <https://auto.gluon.ai/stable/api/autogluon.tabular.models.html>`_ for the list of available
+        tabular models.
+    model_hyperparameters
         Hyperparameters passed to the tabular regression model.
-    eval_metric : str
-        Metric provided as `eval_metric` to the tabular regression model. Must be compatible with `problem_type="regression"`.
-    refit_during_predict : bool
-        If True, the model will be re-trained every time `fit_transform` is called. If False, the model will only be
-        trained the first time that `fit_transform` is called, and future calls to `fit_transform` will only perform a
-        `transform`.
-    max_num_samples : int or None
+    eval_metric
+        Metric provided as ``eval_metric`` to the tabular regression model. Must be compatible with `problem_type="regression"`.
+    refit_during_predict
+        If True, the model will be re-trained every time ``fit_transform`` is called. If False, the model will only be
+        trained the first time that ``fit_transform`` is called, and future calls to ``fit_transform`` will only perform a
+        ``transform``.
+    max_num_samples
         If not None, training dataset passed to regression model will contain at most this many rows.
-    metadata : CovariateMetadata
+    covariate_metadata
         Metadata object describing the covariates available in the dataset.
-    target : str
+    target
         Name of the target column.
-    validation_fraction : float, optional
+    validation_fraction
         Fraction of observations that are reserved as the validation set during training (starting from the end of each
         time series).
-    fit_time_fraction: float
+    fit_time_fraction
         The fraction of the time_limit that will be reserved for model training. The remainder (1 - fit_time_fraction)
         will be reserved for prediction.
 
-        If the estimated prediction time exceeds `(1 - fit_time_fraction) * time_limit`, the regressor will be disabled.
-    include_static_features: bool
+        If the estimated prediction time exceeds ``(1 - fit_time_fraction) * time_limit``, the regressor will be disabled.
+    include_static_features
         If True, static features will be included as features for the regressor.
-    include_item_id: bool
+    include_item_id
         If True, item_id will be included as a categorical feature for the regressor.
     """
 
     def __init__(
         self,
         model_name: str = "CAT",
-        model_hyperparameters: Optional[Dict[str, Any]] = None,
+        model_hyperparameters: dict[str, Any] | None = None,
         eval_metric: str = "mean_absolute_error",
         refit_during_predict: bool = False,
-        max_num_samples: Optional[int] = 500_000,
-        metadata: Optional[CovariateMetadata] = None,
+        max_num_samples: int | None = 500_000,
+        covariate_metadata: CovariateMetadata | None = None,
         target: str = "target",
-        validation_fraction: Optional[float] = 0.1,
+        validation_fraction: float | None = 0.1,
         fit_time_fraction: float = 0.5,
         include_static_features: bool = True,
         include_item_id: bool = False,
     ):
-        if model_name not in TABULAR_MODEL_TYPES:
-            raise ValueError(
-                f"Tabular model {model_name} not supported. Available models: {list(TABULAR_MODEL_TYPES)}"
-            )
         self.target = target
-        self.model_type = TABULAR_MODEL_TYPES[model_name]
+        self.model_type = tabular_ag_model_registry.key_to_cls(model_name)
         self.model_name = model_name
         self.model_hyperparameters = model_hyperparameters or {}
         self.refit_during_predict = refit_during_predict
@@ -81,14 +98,14 @@ class CovariateRegressor:
         self.include_static_features = include_static_features
         self.include_item_id = include_item_id
 
-        self.model: Optional[AbstractModel] = None
+        self.model: AbstractModel | None = None
         self.disabled = False
-        self.metadata = metadata or CovariateMetadata()
+        self.covariate_metadata = covariate_metadata or CovariateMetadata()
 
     def is_fit(self) -> bool:
         return self.model is not None
 
-    def fit(self, data: TimeSeriesDataFrame, time_limit: Optional[float] = None, **kwargs) -> "CovariateRegressor":
+    def fit(self, data: TimeSeriesDataFrame, time_limit: float | None = None, **kwargs) -> "CovariateRegressor":
         """Fit the tabular regressor on the target column using covariates as features."""
         start_time = time.monotonic()
         tabular_df = self._get_tabular_df(data, static_features=data.static_features, include_target=True)
@@ -97,9 +114,9 @@ class CovariateRegressor:
         median_ts_length = data.num_timesteps_per_item().median()
         features_to_drop = [self.target]
         if not self.include_item_id:
-            features_to_drop += [ITEMID]
+            features_to_drop += [TimeSeriesDataFrame.ITEMID]
         if self.validation_fraction is not None:
-            grouped_df = tabular_df.groupby(ITEMID, observed=False, sort=False)
+            grouped_df = tabular_df.groupby(TimeSeriesDataFrame.ITEMID, observed=False, sort=False)
             val_size = max(int(self.validation_fraction * median_ts_length), 1)
             train_df = self._subsample_df(grouped_df.head(-val_size))
             val_df = self._subsample_df(grouped_df.tail(val_size))
@@ -124,6 +141,7 @@ class CovariateRegressor:
             # Has no effect since the model won't be saved to disk.
             # We provide path to avoid https://github.com/autogluon/autogluon/issues/4832
             path="",
+            name=self.model_type.__name__,
         )
         if time_limit is not None:
             time_limit_fit = self.fit_time_fraction * (time_limit - (time.monotonic() - start_time))
@@ -155,7 +173,7 @@ class CovariateRegressor:
         return data
 
     def fit_transform(
-        self, data: TimeSeriesDataFrame, time_limit: Optional[float] = None, **kwargs
+        self, data: TimeSeriesDataFrame, time_limit: float | None = None, **kwargs
     ) -> TimeSeriesDataFrame:
         if not self.is_fit() or self.refit_during_predict:
             self.fit(data=data, time_limit=time_limit, **kwargs)
@@ -165,7 +183,7 @@ class CovariateRegressor:
         self,
         predictions: TimeSeriesDataFrame,
         known_covariates: TimeSeriesDataFrame,
-        static_features: Optional[pd.DataFrame],
+        static_features: pd.DataFrame | None,
     ) -> TimeSeriesDataFrame:
         """Add the tabular regressor predictions to the target column."""
         if not self.disabled:
@@ -173,27 +191,29 @@ class CovariateRegressor:
             predictions = predictions.assign(**{col: predictions[col] + y_pred for col in predictions.columns})
         return predictions
 
-    def _predict(self, data: TimeSeriesDataFrame, static_features: Optional[pd.DataFrame]) -> np.ndarray:
+    def _predict(self, data: TimeSeriesDataFrame, static_features: pd.DataFrame | None) -> np.ndarray:
         """Construct the tabular features matrix and make predictions"""
         assert self.model is not None, "CovariateRegressor must be fit before calling predict."
         tabular_df = self._get_tabular_df(data, static_features=static_features)
         if not self.include_item_id:
-            tabular_df = tabular_df.drop(columns=[ITEMID])
+            tabular_df = tabular_df.drop(columns=[TimeSeriesDataFrame.ITEMID])
         return self.model.predict(X=tabular_df)
 
     def _get_tabular_df(
         self,
         data: TimeSeriesDataFrame,
-        static_features: Optional[pd.DataFrame] = None,
+        static_features: pd.DataFrame | None = None,
         include_target: bool = False,
     ) -> pd.DataFrame:
         """Construct a tabular dataframe from known covariates and static features."""
-        available_columns = [ITEMID] + self.metadata.known_covariates
+        available_columns = [TimeSeriesDataFrame.ITEMID] + self.covariate_metadata.known_covariates
         if include_target:
             available_columns += [self.target]
-        tabular_df = pd.DataFrame(data).reset_index()[available_columns].astype({ITEMID: "category"})
+        tabular_df = (
+            pd.DataFrame(data).reset_index()[available_columns].astype({TimeSeriesDataFrame.ITEMID: "category"})
+        )
         if static_features is not None and self.include_static_features:
-            tabular_df = pd.merge(tabular_df, static_features, on=ITEMID)
+            tabular_df = pd.merge(tabular_df, static_features, on=TimeSeriesDataFrame.ITEMID)
         return tabular_df
 
     def _subsample_df(self, df: pd.DataFrame) -> pd.DataFrame:
@@ -201,3 +221,33 @@ class CovariateRegressor:
         if self.max_num_samples is not None and len(df) > self.max_num_samples:
             df = df.sample(n=self.max_num_samples)
         return df
+
+
+@overload
+def get_covariate_regressor(covariate_regressor: None, target: str, covariate_metadata: CovariateMetadata) -> None: ...
+@overload
+def get_covariate_regressor(
+    covariate_regressor: str | dict, target: str, covariate_metadata: CovariateMetadata
+) -> CovariateRegressor: ...
+def get_covariate_regressor(
+    covariate_regressor: str | dict | None, target: str, covariate_metadata: CovariateMetadata
+) -> CovariateRegressor | None:
+    """Create a CovariateRegressor object based on the value of the `covariate_regressor` hyperparameter."""
+    if covariate_regressor is None:
+        return None
+    elif len(covariate_metadata.known_covariates + covariate_metadata.static_features) == 0:
+        logger.info(
+            "\tSkipping covariate_regressor since the dataset contains no known_covariates or static_features."
+        )
+        return None
+    else:
+        if isinstance(covariate_regressor, str):
+            return GlobalCovariateRegressor(covariate_regressor, target=target, covariate_metadata=covariate_metadata)
+        elif isinstance(covariate_regressor, dict):
+            return GlobalCovariateRegressor(
+                **covariate_regressor, target=target, covariate_metadata=covariate_metadata
+            )
+        else:
+            raise ValueError(
+                f"Invalid value for covariate_regressor {covariate_regressor} of type {type(covariate_regressor)}"
+            )

autogluon/timeseries/splitter.py

@@ -1,6 +1,6 @@
-from typing import Iterator, Optional, Tuple
+from typing import Iterator
 
-from .dataset.ts_dataframe import TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 
 __all__ = [
     "AbstractWindowSplitter",
@@ -13,7 +13,7 @@ class AbstractWindowSplitter:
         self.prediction_length = prediction_length
         self.num_val_windows = num_val_windows
 
-    def split(self, data: TimeSeriesDataFrame) -> Iterator[Tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]]:
+    def split(self, data: TimeSeriesDataFrame) -> Iterator[tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]]:
         raise NotImplementedError
 
 
@@ -33,21 +33,21 @@ class ExpandingWindowSplitter(AbstractWindowSplitter):
 
     Parameters
     ----------
-    prediction_length : int
+    prediction_length
         Length of the forecast horizon.
-    num_val_windows: int, default = 1
+    num_val_windows
         Number of windows to generate from each time series in the dataset.
-    val_step_size : int, optional
+    val_step_size
         The end of each subsequent window is moved this many time steps forward.
     """
 
-    def __init__(self, prediction_length: int, num_val_windows: int = 1, val_step_size: Optional[int] = None):
+    def __init__(self, prediction_length: int, num_val_windows: int = 1, val_step_size: int | None = None):
         super().__init__(prediction_length=prediction_length, num_val_windows=num_val_windows)
         if val_step_size is None:
             val_step_size = prediction_length
         self.val_step_size = val_step_size
 
-    def split(self, data: TimeSeriesDataFrame) -> Iterator[Tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]]:
+    def split(self, data: TimeSeriesDataFrame) -> Iterator[tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]]:
         """Generate train and validation folds for a time series dataset."""
         for window_idx in range(1, self.num_val_windows + 1):
             val_end = -(self.num_val_windows - window_idx) * self.val_step_size
@@ -57,27 +57,3 @@ class ExpandingWindowSplitter(AbstractWindowSplitter):
             train_data = data.slice_by_timestep(None, train_end)
             val_data = data.slice_by_timestep(None, val_end)
             yield train_data, val_data
-
-
-class AbstractTimeSeriesSplitter:
-    def __init__(self, *args, **kwargs):
-        raise ValueError(
-            "`AbstractTimeSeriesSplitter` has been deprecated. "
-            "Please use `autogluon.timeseries.splitter.ExpandingWindowSplitter` instead."
-        )
-
-
-class MultiWindowSplitter(AbstractTimeSeriesSplitter):
-    def __init__(self, *args, **kwargs):
-        raise ValueError(
-            "`MultiWindowSplitter` has been deprecated. "
-            "Please use `autogluon.timeseries.splitter.ExpandingWindowSplitter` instead."
-        )
-
-
-class LastWindowSplitter(MultiWindowSplitter):
-    def __init__(self, *args, **kwargs):
-        raise ValueError(
-            "`LastWindowSplitter` has been deprecated. "
-            "Please use `autogluon.timeseries.splitter.ExpandingWindowSplitter` instead."
-        )

autogluon/timeseries/trainer/__init__.py

@@ -0,0 +1,3 @@
+from .trainer import TimeSeriesTrainer
+
+__all__ = ["TimeSeriesTrainer"]