autogluon.timeseries 1.4.1b20251115__py3-none-any.whl → 1.5.0b20251221__py3-none-any.whl

autogluon/timeseries/models/ensemble/array_based/regressor/per_quantile_tabular.py

@@ -1,12 +1,11 @@
 import logging
-import os
-from typing import Optional
 
 import numpy as np
 import pandas as pd
 from typing_extensions import Self
 
-from autogluon.tabular import TabularPredictor
+from autogluon.tabular.registry import ag_model_registry as tabular_ag_model_registry
+from autogluon.timeseries.utils.timer import SplitTimer
 
 from .abstract import EnsembleRegressor
 
@@ -14,120 +13,82 @@ logger = logging.getLogger(__name__)
 
 
 class PerQuantileTabularEnsembleRegressor(EnsembleRegressor):
-    """TabularPredictor ensemble regressor using separate models per quantile plus dedicated mean model."""
+    """Ensemble regressor using separate models per quantile plus dedicated mean model."""
 
     def __init__(
         self,
-        path: str,
         quantile_levels: list[float],
-        tabular_hyperparameters: Optional[dict] = None,
+        model_name: str,
+        model_hyperparameters: dict | None = None,
     ):
         super().__init__()
-        self.path = path
         self.quantile_levels = quantile_levels
-        self.tabular_hyperparameters = tabular_hyperparameters or {}
-        self.quantile_predictors: list[TabularPredictor] = []
-        self.mean_predictor: Optional[TabularPredictor] = None
-
-    def set_path(self, path: str) -> None:
-        self.path = path
+        model_type = tabular_ag_model_registry.key_to_cls(model_name)
+        model_hyperparameters = model_hyperparameters or {}
+        self.mean_model = model_type(
+            problem_type="regression",
+            hyperparameters=model_hyperparameters,
+            path="",
+            name=f"{model_name}_mean",
+        )
+        self.quantile_models = [
+            model_type(
+                problem_type="quantile",
+                hyperparameters=model_hyperparameters | {"ag.quantile_levels": [quantile]},
+                path="",
+                name=f"{model_name}_q{quantile}",
+            )
+            for quantile in quantile_levels
+        ]
 
     def fit(
         self,
         base_model_mean_predictions: np.ndarray,
         base_model_quantile_predictions: np.ndarray,
         labels: np.ndarray,
-        **kwargs,
+        time_limit: float | None = None,
     ) -> Self:
-        """Fit separate TabularPredictor for mean and each quantile level."""
-        # TODO: implement time_limit
-
         num_windows, num_items, prediction_length = base_model_mean_predictions.shape[:3]
-        target = labels.reshape(num_windows * num_items * prediction_length).ravel()
-
-        # fit mean predictor, based on mean predictions of base models
-        mean_df = self._get_feature_df(base_model_mean_predictions, 0)
-        mean_df["target"] = target
-        self.mean_predictor = TabularPredictor(
-            label="target",
-            path=os.path.join(self.path, "mean"),
-            verbosity=1,
-            problem_type="regression",
-        ).fit(
-            mean_df,
-            hyperparameters=self.tabular_hyperparameters,
-        )
+        y = pd.Series(labels.reshape(num_windows * num_items * prediction_length))
 
-        # fit quantile predictors, each quantile predictor is based on the
-        # estimates of that quantile from base models
-        for i, quantile in enumerate(self.quantile_levels):
-            q_df = self._get_feature_df(base_model_quantile_predictions, i)
-            q_df["target"] = target
+        total_rounds = 1 + len(self.quantile_levels)
+        timer = SplitTimer(time_limit, rounds=total_rounds).start()
 
-            predictor = TabularPredictor(
-                label="target",
-                path=os.path.join(self.path, f"quantile_{quantile}"),
-                verbosity=1,
-                problem_type="regression",
-            ).fit(q_df, hyperparameters=self.tabular_hyperparameters)
-            self.quantile_predictors.append(predictor)
+        # Fit mean model
+        X_mean = self._get_feature_df(base_model_mean_predictions, 0)
+        self.mean_model.fit(X=X_mean, y=y, time_limit=timer.round_time_remaining())
+        timer.next_round()
+
+        # Fit quantile models
+        for i, model in enumerate(self.quantile_models):
+            X_q = self._get_feature_df(base_model_quantile_predictions, i)
+            model.fit(X=X_q, y=y, time_limit=timer.round_time_remaining())
+            timer.next_round()
 
         return self
 
     def _get_feature_df(self, predictions: np.ndarray, index: int) -> pd.DataFrame:
         num_windows, num_items, prediction_length, _, num_models = predictions.shape
         num_tabular_items = num_windows * num_items * prediction_length
-
-        df = pd.DataFrame(
+        return pd.DataFrame(
             predictions[:, :, :, index].reshape(num_tabular_items, num_models),
             columns=[f"model_{mi}" for mi in range(num_models)],
         )
 
-        return df
-
-    def load_predictors(self):
-        if self.mean_predictor is None or len(self.quantile_predictors) < len(self.quantile_levels):
-            try:
-                self.mean_predictor = TabularPredictor.load(os.path.join(self.path, "mean"))
-
-                self.quantile_predictors = []
-                for quantile in self.quantile_levels:
-                    predictor = TabularPredictor.load(os.path.join(self.path, f"quantile_{quantile}"))
-                    self.quantile_predictors.append(predictor)
-
-            except FileNotFoundError:
-                raise ValueError("Model must be fitted before loading for prediction")
-
     def predict(
         self, base_model_mean_predictions: np.ndarray, base_model_quantile_predictions: np.ndarray
     ) -> tuple[np.ndarray, np.ndarray]:
-        self.load_predictors()
-
-        num_windows, num_items, prediction_length, _, _ = base_model_mean_predictions.shape
+        assert self.mean_model.is_fit()
+        num_windows, num_items, prediction_length = base_model_mean_predictions.shape[:3]
         assert num_windows == 1, "Prediction expects a single window to be provided"
 
-        # predict means
-        assert self.mean_predictor is not None
-        mean_predictions = self.mean_predictor.predict(
-            self._get_feature_df(base_model_mean_predictions, 0),
-            as_pandas=False,
-        ).reshape(num_windows, num_items, prediction_length, 1)
+        X_mean = self._get_feature_df(base_model_mean_predictions, 0)
+        mean_predictions = self.mean_model.predict(X_mean).reshape(num_windows, num_items, prediction_length, 1)
 
-        # predict quantiles
         quantile_predictions_list = []
-        for i, predictor in enumerate(self.quantile_predictors):
-            quantile_predictions_list.append(
-                predictor.predict(self._get_feature_df(base_model_quantile_predictions, i), as_pandas=False).reshape(
-                    num_windows, num_items, prediction_length
-                )
-            )
+        for i, model in enumerate(self.quantile_models):
+            X_q = self._get_feature_df(base_model_quantile_predictions, i)
+            quantile_predictions_list.append(model.predict(X_q).reshape(num_windows, num_items, prediction_length))
         quantile_predictions = np.stack(quantile_predictions_list, axis=-1)
 
         return mean_predictions, quantile_predictions
-
-    def __getstate__(self):
-        state = self.__dict__.copy()
-        # Remove predictors to avoid pickling heavy TabularPredictor objects
-        state["mean_predictor"] = None
-        state["quantile_predictors"] = []
-        return state

autogluon/timeseries/models/ensemble/array_based/regressor/tabular.py

@@ -1,11 +1,10 @@
 import logging
-from typing import Optional
 
 import numpy as np
 import pandas as pd
 from typing_extensions import Self
 
-from autogluon.tabular import TabularPredictor
+from autogluon.tabular.registry import ag_model_registry as tabular_ag_model_registry
 
 from .abstract import EnsembleRegressor
 
@@ -13,55 +12,36 @@ logger = logging.getLogger(__name__)
 
 
 class TabularEnsembleRegressor(EnsembleRegressor):
-    """TabularPredictor ensemble regressor using AutoGluon-Tabular as a single
-    quantile regressor for the target.
-    """
+    """Ensemble regressor based on a single model from AutoGluon-Tabular that predicts all quantiles simultaneously."""
 
     def __init__(
         self,
-        path: str,
         quantile_levels: list[float],
-        tabular_hyperparameters: Optional[dict] = None,
+        model_name: str,
+        model_hyperparameters: dict | None = None,
     ):
         super().__init__()
-        self.path = path
         self.quantile_levels = quantile_levels
-        self.tabular_hyperparameters = tabular_hyperparameters or {}
-        self.predictor: Optional[TabularPredictor] = None
-
-    def set_path(self, path: str) -> None:
-        self.path = path
+        model_type = tabular_ag_model_registry.key_to_cls(model_name)
+        model_hyperparameters = model_hyperparameters or {}
+        self.model = model_type(
+            problem_type="quantile",
+            hyperparameters=model_hyperparameters | {"ag.quantile_levels": quantile_levels},
+            path="",
+            name=model_name,
+        )
 
     def fit(
         self,
         base_model_mean_predictions: np.ndarray,
         base_model_quantile_predictions: np.ndarray,
         labels: np.ndarray,
-        time_limit: Optional[int] = None,
-        **kwargs,
+        time_limit: float | None = None,
     ) -> Self:
-        self.predictor = TabularPredictor(
-            path=self.path,
-            label="target",
-            problem_type="quantile",
-            quantile_levels=self.quantile_levels,
-            verbosity=1,
-        )
-
-        # get features
-        df = self._get_feature_df(base_model_mean_predictions, base_model_quantile_predictions)
-
-        # get labels
+        X = self._get_feature_df(base_model_mean_predictions, base_model_quantile_predictions)
         num_windows, num_items, prediction_length = base_model_mean_predictions.shape[:3]
-        label_series = labels.reshape(num_windows * num_items * prediction_length)
-        df["target"] = label_series
-
-        self.predictor.fit(
-            df,
-            hyperparameters=self.tabular_hyperparameters,
-            time_limit=time_limit,  # type: ignore
-        )
-
+        y = pd.Series(labels.reshape(num_windows * num_items * prediction_length))
+        self.model.fit(X=X, y=y, time_limit=time_limit)
         return self
 
     def predict(
@@ -69,18 +49,13 @@ class TabularEnsembleRegressor(EnsembleRegressor):
         base_model_mean_predictions: np.ndarray,
         base_model_quantile_predictions: np.ndarray,
     ) -> tuple[np.ndarray, np.ndarray]:
-        if self.predictor is None:
-            try:
-                self.predictor = TabularPredictor.load(self.path)
-            except FileNotFoundError:
-                raise ValueError("Model must be fitted before prediction")
-
+        assert self.model.is_fit()
         num_windows, num_items, prediction_length = base_model_mean_predictions.shape[:3]
         assert num_windows == 1, "Prediction expects a single window to be provided"
 
-        df = self._get_feature_df(base_model_mean_predictions, base_model_quantile_predictions)
+        X = self._get_feature_df(base_model_mean_predictions, base_model_quantile_predictions)
 
-        pred = self.predictor.predict(df, as_pandas=False)
+        pred = self.model.predict(X)
 
         # Reshape back to (num_windows, num_items, prediction_length, num_quantiles)
         pred = pred.reshape(num_windows, num_items, prediction_length, len(self.quantile_levels))
@@ -99,16 +74,13 @@ class TabularEnsembleRegressor(EnsembleRegressor):
     ) -> pd.DataFrame:
         num_windows, num_items, prediction_length, _, num_models = base_model_mean_predictions.shape
         num_tabular_items = num_windows * num_items * prediction_length
-
-        X = np.hstack(
+        features_array = np.hstack(
             [
                 base_model_mean_predictions.reshape(num_tabular_items, -1),
                 base_model_quantile_predictions.reshape(num_tabular_items, -1),
             ]
         )
-
-        df = pd.DataFrame(X, columns=self._get_feature_names(num_models))
-        return df
+        return pd.DataFrame(features_array, columns=self._get_feature_names(num_models))
 
     def _get_feature_names(self, num_models: int) -> list[str]:
         feature_names = []
@@ -133,9 +105,3 @@ class TabularEnsembleRegressor(EnsembleRegressor):
             )
 
         return median_idx
-
-    def __getstate__(self):
-        state = self.__dict__.copy()
-        # Remove the predictor to avoid pickling heavy TabularPredictor objects
-        state["predictor"] = None
-        return state

autogluon/timeseries/models/ensemble/ensemble_selection.py

@@ -0,0 +1,167 @@
+import copy
+
+import numpy as np
+
+import autogluon.core as ag
+from autogluon.core.models.greedy_ensemble.ensemble_selection import EnsembleSelection
+from autogluon.timeseries import TimeSeriesDataFrame
+from autogluon.timeseries.metrics import TimeSeriesScorer
+from autogluon.timeseries.utils.datetime import get_seasonality
+
+
+class TimeSeriesEnsembleSelection(EnsembleSelection):
+    def __init__(
+        self,
+        ensemble_size: int,
+        metric: TimeSeriesScorer,
+        problem_type: str = ag.constants.QUANTILE,
+        sorted_initialization: bool = False,
+        bagging: bool = False,
+        tie_breaker: str = "random",
+        random_state: np.random.RandomState | None = None,
+        prediction_length: int = 1,
+        target: str = "target",
+        **kwargs,
+    ):
+        super().__init__(
+            ensemble_size=ensemble_size,
+            metric=metric,  # type: ignore
+            problem_type=problem_type,
+            sorted_initialization=sorted_initialization,
+            bagging=bagging,
+            tie_breaker=tie_breaker,
+            random_state=random_state,
+            **kwargs,
+        )
+        self.prediction_length = prediction_length
+        self.target = target
+        self.metric: TimeSeriesScorer
+
+        self.dummy_pred_per_window = []
+        self.scorer_per_window = []
+
+        self.dummy_pred_per_window: list[TimeSeriesDataFrame] | None
+        self.scorer_per_window: list[TimeSeriesScorer] | None
+        self.data_future_per_window: list[TimeSeriesDataFrame] | None
+
+    def fit(  # type: ignore
+        self,
+        predictions: list[list[TimeSeriesDataFrame]],
+        labels: list[TimeSeriesDataFrame],
+        time_limit: float | None = None,
+    ):
+        return super().fit(
+            predictions=predictions,  # type: ignore
+            labels=labels,  # type: ignore
+            time_limit=time_limit,
+        )
+
+    def _fit(  # type: ignore
+        self,
+        predictions: list[list[TimeSeriesDataFrame]],
+        labels: list[TimeSeriesDataFrame],
+        time_limit: float | None = None,
+        sample_weight: list[float] | None = None,
+    ):
+        # Stack predictions for each model into a 3d tensor of shape [num_val_windows, num_rows, num_cols]
+        stacked_predictions = [np.stack(preds) for preds in predictions]
+
+        self.dummy_pred_per_window = []
+        self.scorer_per_window = []
+        self.data_future_per_window = []
+
+        seasonal_period = self.metric.seasonal_period
+        if seasonal_period is None:
+            seasonal_period = get_seasonality(labels[0].freq)
+
+        for window_idx, data in enumerate(labels):
+            dummy_pred = copy.deepcopy(predictions[0][window_idx])
+            # This should never happen; sanity check to make sure that all predictions have the same index
+            assert all(dummy_pred.index.equals(pred[window_idx].index) for pred in predictions)
+            assert all(dummy_pred.columns.equals(pred[window_idx].columns) for pred in predictions)
+
+            self.dummy_pred_per_window.append(dummy_pred)
+
+            scorer = copy.deepcopy(self.metric)
+            # Split the observed time series once to avoid repeated computations inside the evaluator
+            data_past = data.slice_by_timestep(None, -self.prediction_length)
+            data_future = data.slice_by_timestep(-self.prediction_length, None)
+            scorer.save_past_metrics(data_past, target=self.target, seasonal_period=seasonal_period)
+            self.scorer_per_window.append(scorer)
+            self.data_future_per_window.append(data_future)
+
+        super()._fit(
+            predictions=stacked_predictions,
+            labels=data_future,  # type: ignore
+            time_limit=time_limit,
+        )
+        self.dummy_pred_per_window = None
+        self.evaluator_per_window = None
+        self.data_future_per_window = None
+
+    def _calculate_regret(  # type: ignore
+        self,
+        y_true,
+        y_pred_proba,
+        metric: TimeSeriesScorer,
+        sample_weight=None,
+    ):
+        # Compute average score across all validation windows
+        total_score = 0.0
+
+        assert self.data_future_per_window is not None
+        assert self.dummy_pred_per_window is not None
+        assert self.scorer_per_window is not None
+
+        for window_idx, data_future in enumerate(self.data_future_per_window):
+            dummy_pred = self.dummy_pred_per_window[window_idx]
+            dummy_pred[list(dummy_pred.columns)] = y_pred_proba[window_idx]
+            # We use scorer.compute_metric instead of scorer.score to avoid repeated calls to scorer.save_past_metrics
+            metric_value = self.scorer_per_window[window_idx].compute_metric(
+                data_future,
+                dummy_pred,
+                target=self.target,
+            )
+            total_score += metric.sign * metric_value
+        avg_score = total_score / len(self.data_future_per_window)
+        # score: higher is better, regret: lower is better, so we flip the sign
+        return -avg_score
+
+
+def fit_time_series_ensemble_selection(
+    data_per_window: list[TimeSeriesDataFrame],
+    predictions_per_window: dict[str, list[TimeSeriesDataFrame]],
+    ensemble_size: int,
+    eval_metric: TimeSeriesScorer,
+    prediction_length: int = 1,
+    target: str = "target",
+    time_limit: float | None = None,
+) -> dict[str, float]:
+    """Fit ensemble selection for time series forecasting and return ensemble weights.
+
+    Parameters
+    ----------
+    data_per_window:
+        List of ground truth time series data for each validation window.
+    predictions_per_window:
+        Dictionary mapping model names to their predictions for each validation window.
+    ensemble_size:
+        Number of iterations of the ensemble selection algorithm.
+
+    Returns
+    -------
+    weights:
+        Dictionary mapping the model name to its weight in the ensemble.
+    """
+    ensemble_selection = TimeSeriesEnsembleSelection(
+        ensemble_size=ensemble_size,
+        metric=eval_metric,
+        prediction_length=prediction_length,
+        target=target,
+    )
+    ensemble_selection.fit(
+        predictions=list(predictions_per_window.values()),
+        labels=data_per_window,
+        time_limit=time_limit,
+    )
+    return {model: float(weight) for model, weight in zip(predictions_per_window.keys(), ensemble_selection.weights_)}

autogluon/timeseries/models/ensemble/per_item_greedy.py

@@ -0,0 +1,172 @@
+import logging
+import pprint
+import time
+from typing import Any
+
+import pandas as pd
+from joblib import Parallel, delayed
+
+from autogluon.timeseries import TimeSeriesDataFrame
+from autogluon.timeseries.utils.constants import AG_DEFAULT_N_JOBS
+
+from .abstract import AbstractTimeSeriesEnsembleModel
+from .ensemble_selection import fit_time_series_ensemble_selection
+
+logger = logging.getLogger(__name__)
+
+
+class PerItemGreedyEnsemble(AbstractTimeSeriesEnsembleModel):
+    """Per-item greedy ensemble that fits separate weighted ensembles for each individual time series.
+
+    This ensemble applies the greedy Ensemble Selection algorithm by Caruana et al. [Car2004]_ independently
+    to each time series in the dataset, allowing for customized model combinations that adapt to the
+    specific characteristics of individual series. Each time series gets its own optimal ensemble weights
+    based on predictions for that particular series. If items not seen during training are provided at prediction
+    time, average model weight across the training items will be used for their predictions.
+
+    The per-item approach is particularly effective for datasets with heterogeneous time series that
+    exhibit different patterns, seasonalities, or noise characteristics.
+
+    The algorithm uses parallel processing to efficiently fit ensembles across all time series.
+
+    Other Parameters
+    ----------------
+    ensemble_size : int, default = 100
+        Number of models (with replacement) to include in the ensemble.
+    n_jobs : int or float, default = joblib.cpu_count(only_physical_cores=True)
+        Number of CPU cores used to fit the ensembles in parallel.
+
+    References
+    ----------
+    .. [Car2004] Caruana, Rich, et al. "Ensemble selection from libraries of models."
+        Proceedings of the twenty-first international conference on Machine learning. 2004.
+    """
+
+    def __init__(self, name: str | None = None, **kwargs):
+        if name is None:
+            name = "PerItemWeightedEnsemble"
+        super().__init__(name=name, **kwargs)
+        self.weights_df: pd.DataFrame
+        self.average_weight: pd.Series
+
+    @property
+    def model_names(self) -> list[str]:
+        return list(self.weights_df.columns)
+
+    def _get_default_hyperparameters(self) -> dict[str, Any]:
+        return {"ensemble_size": 100, "n_jobs": AG_DEFAULT_N_JOBS}
+
+    def _fit(
+        self,
+        predictions_per_window: dict[str, list[TimeSeriesDataFrame]],
+        data_per_window: list[TimeSeriesDataFrame],
+        model_scores: dict[str, float] | None = None,
+        time_limit: float | None = None,
+    ) -> None:
+        model_names = list(predictions_per_window.keys())
+        item_ids = data_per_window[0].item_ids
+        n_jobs = min(self.get_hyperparameter("n_jobs"), len(item_ids))
+
+        predictions_per_item = self._split_predictions_per_item(predictions_per_window)
+        data_per_item = self._split_data_per_item(data_per_window)
+
+        ensemble_selection_kwargs = dict(
+            ensemble_size=self.get_hyperparameter("ensemble_size"),
+            eval_metric=self.eval_metric,
+            prediction_length=self.prediction_length,
+            target=self.target,
+        )
+
+        time_limit_per_item = None if time_limit is None else time_limit * n_jobs / len(item_ids)
+        end_time = None if time_limit is None else time.time() + time_limit
+
+        # Fit ensemble for each item in parallel
+        executor = Parallel(n_jobs=n_jobs)
+        weights_per_item = executor(
+            delayed(self._fit_item_ensemble)(
+                data_per_item[item_id],
+                predictions_per_item[item_id],
+                time_limit_per_item=time_limit_per_item,
+                end_time=end_time,
+                **ensemble_selection_kwargs,
+            )
+            for item_id in item_ids
+        )
+        self.weights_df = pd.DataFrame(weights_per_item, index=item_ids, columns=model_names)  # type: ignore
+        self.average_weight = self.weights_df.mean(axis=0)
+
+        # Drop models with zero average weight
+        if (self.average_weight == 0).any():
+            models_to_keep = self.average_weight[self.average_weight > 0].index
+            self.weights_df = self.weights_df[models_to_keep]
+            self.average_weight = self.average_weight[models_to_keep]
+
+        weights_for_printing = {model: round(float(weight), 2) for model, weight in self.average_weight.items()}
+        logger.info(f"\tAverage ensemble weights: {pprint.pformat(weights_for_printing, width=1000)}")
+
+    def _split_predictions_per_item(
+        self, predictions_per_window: dict[str, list[TimeSeriesDataFrame]]
+    ) -> dict[str, dict[str, list[TimeSeriesDataFrame]]]:
+        """Build a dictionary mapping item_id -> dict[model_name, list[TimeSeriesDataFrame]]."""
+        item_ids = list(predictions_per_window.values())[0][0].item_ids
+
+        predictions_per_item = {}
+        for i, item_id in enumerate(item_ids):
+            item_predictions = {}
+            for model_name, preds_per_window in predictions_per_window.items():
+                item_preds_per_window = [
+                    pred.iloc[i * self.prediction_length : (i + 1) * self.prediction_length]
+                    for pred in preds_per_window
+                ]
+                item_predictions[model_name] = item_preds_per_window
+            predictions_per_item[item_id] = item_predictions
+        return predictions_per_item
+
+    def _split_data_per_item(self, data_per_window: list[TimeSeriesDataFrame]) -> dict[str, list[TimeSeriesDataFrame]]:
+        """Build a dictionary mapping item_id -> ground truth values across all windows."""
+        item_ids = data_per_window[0].item_ids
+        data_per_item = {item_id: [] for item_id in item_ids}
+
+        for data in data_per_window:
+            indptr = data.get_indptr()
+            for item_idx, item_id in enumerate(item_ids):
+                new_slice = data.iloc[indptr[item_idx] : indptr[item_idx + 1]]
+                data_per_item[item_id].append(new_slice)
+        return data_per_item
+
+    @staticmethod
+    def _fit_item_ensemble(
+        data_per_window: list[TimeSeriesDataFrame],
+        predictions_per_window: dict[str, list[TimeSeriesDataFrame]],
+        time_limit_per_item: float | None = None,
+        end_time: float | None = None,
+        **ensemble_selection_kwargs,
+    ) -> dict[str, float]:
+        """Fit ensemble for a single item."""
+        if end_time is not None:
+            assert time_limit_per_item is not None
+            time_left = end_time - time.time()
+            time_limit_per_item = min(time_limit_per_item, time_left)
+        return fit_time_series_ensemble_selection(
+            data_per_window, predictions_per_window, time_limit=time_limit_per_item, **ensemble_selection_kwargs
+        )
+
+    def _predict(self, data: dict[str, TimeSeriesDataFrame], **kwargs) -> TimeSeriesDataFrame:
+        assert all(model in data for model in self.weights_df.columns)
+        item_ids = list(data.values())[0].item_ids
+        unseen_item_ids = set(item_ids) - set(self.weights_df.index)
+        if unseen_item_ids:
+            logger.debug(f"Using average weights for {len(unseen_item_ids)} unseen items")
+        weights = self.weights_df.reindex(item_ids).fillna(self.average_weight)
+
+        result = None
+        for model_name in self.weights_df.columns:
+            model_pred = data[model_name]
+            model_weights = weights[model_name].to_numpy().repeat(self.prediction_length)
+            weighted_pred = model_pred.to_data_frame().multiply(model_weights, axis=0)
+            result = weighted_pred if result is None else result + weighted_pred
+
+        return TimeSeriesDataFrame(result)  # type: ignore
+
+    def remap_base_models(self, model_refit_map: dict[str, str]) -> None:
+        self.weights_df.rename(columns=model_refit_map, inplace=True)

autogluon/timeseries/models/ensemble/weighted/abstract.py

@@ -1,6 +1,5 @@
 import functools
 from abc import ABC
-from typing import Optional
 
 import numpy as np
 
@@ -10,9 +9,14 @@ from ..abstract import AbstractTimeSeriesEnsembleModel
 
 
 class AbstractWeightedTimeSeriesEnsembleModel(AbstractTimeSeriesEnsembleModel, ABC):
-    """Abstract class for weighted ensembles which assign one (global) weight per model."""
+    """Abstract base class for weighted ensemble models that assign global weights to base models.
 
-    def __init__(self, name: Optional[str] = None, **kwargs):
+    Weighted ensembles combine predictions from multiple base models using learned or computed weights,
+    where each base model receives a single global weight applied across all time series and forecast
+    horizons. The final prediction is computed as a weighted linear combination of base model forecasts.
+    """
+
+    def __init__(self, name: str | None = None, **kwargs):
         super().__init__(name=name, **kwargs)
         self.model_to_weight: dict[str, float] = {}