autogluon.timeseries 1.4.1b20251010__py3-none-any.whl → 1.4.1b20251115__py3-none-any.whl

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

@@ -0,0 +1,41 @@
+import functools
+from abc import ABC
+from typing import Optional
+
+import numpy as np
+
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
+
+from ..abstract import AbstractTimeSeriesEnsembleModel
+
+
+class AbstractWeightedTimeSeriesEnsembleModel(AbstractTimeSeriesEnsembleModel, ABC):
+    """Abstract class for weighted ensembles which assign one (global) weight per model."""
+
+    def __init__(self, name: Optional[str] = None, **kwargs):
+        super().__init__(name=name, **kwargs)
+        self.model_to_weight: dict[str, float] = {}
+
+    @property
+    def model_names(self) -> list[str]:
+        return list(self.model_to_weight.keys())
+
+    @property
+    def model_weights(self) -> np.ndarray:
+        return np.array(list(self.model_to_weight.values()), dtype=np.float64)
+
+    def _predict(self, data: dict[str, TimeSeriesDataFrame], **kwargs) -> TimeSeriesDataFrame:
+        weighted_predictions = [data[model_name] * weight for model_name, weight in self.model_to_weight.items()]
+        return functools.reduce(lambda x, y: x + y, weighted_predictions)
+
+    def get_info(self) -> dict:
+        info = super().get_info()
+        info["model_weights"] = self.model_to_weight.copy()
+        return info
+
+    def remap_base_models(self, model_refit_map: dict[str, str]) -> None:
+        updated_weights = {}
+        for model, weight in self.model_to_weight.items():
+            model_full_name = model_refit_map.get(model, model)
+            updated_weights[model_full_name] = weight
+        self.model_to_weight = updated_weights

autogluon/timeseries/models/ensemble/{basic.py → weighted/basic.py}

@@ -10,11 +10,6 @@ from .abstract import AbstractWeightedTimeSeriesEnsembleModel
 class SimpleAverageEnsemble(AbstractWeightedTimeSeriesEnsembleModel):
     """Constructs a weighted ensemble using a simple average of the constituent models' predictions."""
 
-    def __init__(self, name: Optional[str] = None, **kwargs):
-        if name is None:
-            name = "SimpleAverageEnsemble"
-        super().__init__(name=name, **kwargs)
-
     def _fit(
         self,
         predictions_per_window: dict[str, list[TimeSeriesDataFrame]],
@@ -47,11 +42,6 @@ class PerformanceWeightedEnsemble(AbstractWeightedTimeSeriesEnsembleModel):
         36.1 (2020): 93-97.
     """
 
-    def __init__(self, name: Optional[str] = None, **kwargs):
-        if name is None:
-            name = "PerformanceWeightedEnsemble"
-        super().__init__(name=name, **kwargs)
-
     def _get_default_hyperparameters(self) -> dict[str, Any]:
         return {"weight_scheme": "sqrt"}
 

autogluon/timeseries/models/gluonts/abstract.py

@@ -21,7 +21,7 @@ from autogluon.core.hpo.constants import RAY_BACKEND
 from autogluon.tabular.models.tabular_nn.utils.categorical_encoders import (
     OneHotMergeRaresHandleUnknownEncoder as OneHotEncoder,
 )
-from autogluon.timeseries.dataset.ts_dataframe import ITEMID, TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.models.abstract import AbstractTimeSeriesModel
 from autogluon.timeseries.utils.warning_filters import disable_root_logger, warning_filter
 
@@ -566,7 +566,7 @@ class AbstractGluonTSModel(AbstractTimeSeriesModel):
     ) -> TimeSeriesDataFrame:
         from gluonts.torch.model.forecast import DistributionForecast
 
-        item_ids = forecast_index.unique(level=ITEMID)
+        item_ids = forecast_index.unique(level=TimeSeriesDataFrame.ITEMID)
         if isinstance(forecasts[0], SampleForecast):
             forecast_df = self._stack_sample_forecasts(cast(list[SampleForecast], forecasts), item_ids)
         elif isinstance(forecasts[0], QuantileForecast):

autogluon/timeseries/models/gluonts/dataset.py

@@ -5,7 +5,7 @@ import pandas as pd
 from gluonts.dataset.common import Dataset as GluonTSDataset
 from gluonts.dataset.field_names import FieldName
 
-from autogluon.timeseries.dataset.ts_dataframe import TIMESTAMP, TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.utils.datetime import norm_freq_str
 
 
@@ -44,7 +44,7 @@ class SimpleGluonTSDataset(GluonTSDataset):
         # Replace inefficient groupby ITEMID with indptr that stores start:end of each time series
         self.item_ids = target_df.item_ids
         self.indptr = target_df.get_indptr()
-        self.start_timestamps = target_df.index[self.indptr[:-1]].to_frame(index=False)[TIMESTAMP]
+        self.start_timestamps = target_df.index[self.indptr[:-1]].to_frame(index=False)[TimeSeriesDataFrame.TIMESTAMP]
         assert len(self.item_ids) == len(self.start_timestamps)
 
     @staticmethod

autogluon/timeseries/models/local/abstract_local_model.py

@@ -9,7 +9,7 @@ from joblib import Parallel, cpu_count, delayed
 from scipy.stats import norm
 
 from autogluon.core.utils.exceptions import TimeLimitExceeded
-from autogluon.timeseries.dataset.ts_dataframe import ITEMID, TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.metrics import TimeSeriesScorer
 from autogluon.timeseries.models.abstract import AbstractTimeSeriesModel
 from autogluon.timeseries.utils.datetime import get_seasonality
@@ -145,7 +145,7 @@ class AbstractLocalModel(AbstractTimeSeriesModel):
             data = data.slice_by_timestep(-max_ts_length, None)
 
         indptr = data.get_indptr()
-        target_series = data[self.target].droplevel(level=ITEMID)
+        target_series = data[self.target].droplevel(level=TimeSeriesDataFrame.ITEMID)
         all_series = (target_series[indptr[i] : indptr[i + 1]] for i in range(len(indptr) - 1))
 
         # timeout ensures that no individual job takes longer than time_limit

autogluon/timeseries/models/multi_window/multi_window_model.py

@@ -10,7 +10,7 @@ import numpy as np
 from typing_extensions import Self
 
 import autogluon.core as ag
-from autogluon.timeseries.dataset.ts_dataframe import TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.models.abstract import AbstractTimeSeriesModel
 from autogluon.timeseries.models.local.abstract_local_model import AbstractLocalModel
 from autogluon.timeseries.splitter import AbstractWindowSplitter, ExpandingWindowSplitter

autogluon/timeseries/models/toto/model.py

@@ -25,9 +25,11 @@ class TotoModel(AbstractTimeSeriesModel):
     architecture that autoregressively outputs parametric distribution forecasts. More details can be found on
     `Hugging Face <https://huggingface.co/Datadog/Toto-Open-Base-1.0>`_ and `GitHub <https://github.com/DataDog/toto>`_.
 
-    The AutoGluon implementation of Toto is on a port of the original implementation. It is optimized for easy maintenance
-    with the rest of the AutoGluon model zoo, and does not feature some important optimizations such as xformers and flash-attention
-    available in the original model repository. The AutoGluon implementation of Toto requires a CUDA-compatible GPU.
+    The AutoGluon implementation of Toto is on a port of the original implementation. AutoGluon supports Toto for
+    **inference only**, i.e., the model will not be trained or fine-tuned on the provided training data. Toto is optimized
+    for easy maintenance with the rest of the AutoGluon model zoo, and does not feature some important optimizations such
+    as xformers and flash-attention available in the original model repository. The AutoGluon implementation of Toto
+    requires a CUDA-compatible GPU.
 
     References
     ----------

autogluon/timeseries/predictor.py

@@ -22,10 +22,9 @@ from autogluon.core.utils.loaders import load_pkl, load_str
 from autogluon.core.utils.savers import save_pkl, save_str
 from autogluon.timeseries import __version__ as current_ag_version
 from autogluon.timeseries.configs import get_predictor_presets
-from autogluon.timeseries.dataset.ts_dataframe import ITEMID, TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.learner import TimeSeriesLearner
 from autogluon.timeseries.metrics import TimeSeriesScorer, check_get_evaluation_metric
-from autogluon.timeseries.splitter import ExpandingWindowSplitter
 from autogluon.timeseries.trainer import TimeSeriesTrainer
 from autogluon.timeseries.utils.forecast import make_future_data_frame
 
@@ -221,20 +220,6 @@ class TimeSeriesPredictor:
             ensemble_model_type=kwargs.pop("ensemble_model_type", None),
         )
 
-        if "ignore_time_index" in kwargs:
-            raise TypeError(
-                "`ignore_time_index` argument to TimeSeriesPredictor.__init__() has been deprecated.\n"
-                "If your data has irregular timestamps, please either 1) specify the desired regular frequency when "
-                "creating the predictor as `TimeSeriesPredictor(freq=...)` or 2) manually convert timestamps to "
-                "regular frequency with `data.convert_frequency(freq=...)`."
-            )
-        for k in ["learner_type", "learner_kwargs"]:
-            if k in kwargs:
-                val = kwargs.pop(k)
-                logger.warning(
-                    f"Passing `{k}` to TimeSeriesPredictor has been deprecated and will be removed in v1.4. "
-                    f"The provided value {val} will be ignored."
-                )
         if len(kwargs) > 0:
             for key in kwargs:
                 raise TypeError(f"TimeSeriesPredictor.__init__() got an unexpected keyword argument '{key}'")
@@ -417,7 +402,9 @@ class TimeSeriesPredictor:
             )
             train_data = train_data.query("item_id not in @too_short_items")
 
-        all_nan_items = train_data.item_ids[train_data[self.target].isna().groupby(ITEMID, sort=False).all()]
+        all_nan_items = train_data.item_ids[
+            train_data[self.target].isna().groupby(TimeSeriesDataFrame.ITEMID, sort=False).all()
+        ]
         if len(all_nan_items) > 0:
             logger.info(f"\tRemoving {len(all_nan_items)} time series consisting of only NaN values from train_data.")
             train_data = train_data.query("item_id not in @all_nan_items")
@@ -751,10 +738,6 @@ class TimeSeriesPredictor:
                 train_data, num_val_windows=num_val_windows, val_step_size=val_step_size
             )
 
-        val_splitter = ExpandingWindowSplitter(
-            prediction_length=self.prediction_length, num_val_windows=num_val_windows, val_step_size=val_step_size
-        )
-
         time_left = None if time_limit is None else time_limit - (time.time() - time_start)
         self._learner.fit(
             train_data=train_data,
@@ -764,7 +747,8 @@ class TimeSeriesPredictor:
             excluded_model_types=excluded_model_types,
             time_limit=time_left,
             verbosity=verbosity,
-            val_splitter=val_splitter,
+            num_val_windows=num_val_windows,
+            val_step_size=val_step_size,
             refit_every_n_windows=refit_every_n_windows,
             skip_model_selection=skip_model_selection,
             enable_ensemble=enable_ensemble,
@@ -866,7 +850,7 @@ class TimeSeriesPredictor:
             use_cache=use_cache,
             random_seed=random_seed,
         )
-        return cast(TimeSeriesDataFrame, predictions.reindex(original_item_id_order, level=ITEMID))
+        return cast(TimeSeriesDataFrame, predictions.reindex(original_item_id_order, level=TimeSeriesDataFrame.ITEMID))
 
     def evaluate(
         self,
@@ -1498,7 +1482,7 @@ class TimeSeriesPredictor:
         )
 
         y_val: list[TimeSeriesDataFrame] = [
-            select_target(df) for df in trainer._get_ensemble_oof_data(train_data=train_data, val_data=val_data)
+            select_target(df) for df in trainer._get_validation_windows(train_data=train_data, val_data=val_data)
         ]
         y_test: TimeSeriesDataFrame = select_target(test_data)
 
@@ -1621,7 +1605,7 @@ class TimeSeriesPredictor:
                         for q in quantile_levels:
                             ax.fill_between(forecast.index, point_forecast, forecast[str(q)], color="C1", alpha=0.2)
             if len(axes) > len(item_ids):
-                axes[len(item_ids)].set_axis_off()
-            handles, labels = axes[0].get_legend_handles_labels()
+                axes[len(item_ids)].set_axis_off()  # type: ignore
+            handles, labels = axes[0].get_legend_handles_labels()  # type: ignore
             fig.legend(handles, labels, bbox_to_anchor=(0.5, 0.0), ncols=len(handles))
         return fig

autogluon/timeseries/regressor.py

@@ -7,7 +7,7 @@ import pandas as pd
 
 from autogluon.core.models import AbstractModel
 from autogluon.tabular.registry import ag_model_registry as tabular_ag_model_registry
-from autogluon.timeseries.dataset.ts_dataframe import ITEMID, TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.utils.features import CovariateMetadata
 
 logger = logging.getLogger(__name__)
@@ -119,9 +119,9 @@ class GlobalCovariateRegressor(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))
@@ -201,7 +201,7 @@ class GlobalCovariateRegressor(CovariateRegressor):
         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(
@@ -211,12 +211,14 @@ class GlobalCovariateRegressor(CovariateRegressor):
         include_target: bool = False,
     ) -> pd.DataFrame:
         """Construct a tabular dataframe from known covariates and static features."""
-        available_columns = [ITEMID] + self.covariate_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:

autogluon/timeseries/splitter.py

@@ -1,6 +1,6 @@
 from typing import Iterator, Optional
 
-from .dataset.ts_dataframe import TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 
 __all__ = [
     "AbstractWindowSplitter",
@@ -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/ensemble_composer.py

@@ -0,0 +1,250 @@
+import logging
+import os
+import time
+import traceback
+from typing import Iterator, Optional
+
+import networkx as nx
+import numpy as np
+from typing_extensions import Self
+
+from autogluon.timeseries import TimeSeriesDataFrame
+from autogluon.timeseries.metrics import TimeSeriesScorer
+from autogluon.timeseries.models.ensemble import AbstractTimeSeriesEnsembleModel, get_ensemble_class
+from autogluon.timeseries.splitter import AbstractWindowSplitter
+from autogluon.timeseries.utils.warning_filters import warning_filter
+
+from .utils import log_scores_and_times
+
+logger = logging.getLogger("autogluon.timeseries.trainer")
+
+
+class EnsembleComposer:
+    """Helper class for TimeSeriesTrainer to build multi-layer stack ensembles."""
+
+    def __init__(
+        self,
+        path,
+        prediction_length: int,
+        eval_metric: TimeSeriesScorer,
+        target: str,
+        quantile_levels: list[float],
+        model_graph: nx.DiGraph,
+        ensemble_hyperparameters: dict,
+        window_splitter: AbstractWindowSplitter,
+    ):
+        self.eval_metric = eval_metric
+        self.path = path
+        self.prediction_length = prediction_length
+        self.target = target
+        self.quantile_levels = quantile_levels
+
+        self.ensemble_hyperparameters = ensemble_hyperparameters
+
+        self.window_splitter = window_splitter
+
+        self.banned_model_names = list(model_graph.nodes)
+        self.model_graph = self._get_base_model_graph(source_graph=model_graph)
+
+    @staticmethod
+    def _get_base_model_graph(source_graph: nx.DiGraph) -> nx.DiGraph:
+        """Return a model graph by copying only base models (nodes without predecessors)
+        This ensures we start fresh for ensemble building.
+        """
+        rootset = EnsembleComposer._get_rootset(source_graph)
+
+        dst_graph = nx.DiGraph()
+        for node in rootset:
+            dst_graph.add_node(node, **source_graph.nodes[node])
+
+        return dst_graph
+
+    @staticmethod
+    def _get_rootset(graph: nx.DiGraph) -> list[str]:
+        return [n for n in graph.nodes if not list(graph.predecessors(n))]
+
+    def iter_ensembles(self) -> Iterator[tuple[int, AbstractTimeSeriesEnsembleModel, list[str]]]:
+        """Iterate over trained ensemble models, layer by layer.
+
+        Yields
+        ------
+        layer_ix
+            The layer index of the ensemble.
+        model
+            The ensemble model object
+        base_model_names
+            The names of the base models that are part of the ensemble.
+        """
+        rootset = self._get_rootset(self.model_graph)
+
+        for layer_ix, layer in enumerate(nx.traversal.bfs_layers(self.model_graph, rootset)):
+            if layer_ix == 0:  # we don't need base models
+                continue
+
+            for model_name in layer:
+                attrs = self.model_graph.nodes[model_name]
+                model_path = os.path.join(self.path, *attrs["path"])
+                model = attrs["type"].load(path=model_path)
+
+                yield (
+                    layer_ix,
+                    model,
+                    list(self.model_graph.predecessors(model_name)),
+                )
+
+    def fit(
+        self,
+        train_data: TimeSeriesDataFrame,
+        val_data: Optional[TimeSeriesDataFrame] = None,
+        time_limit: Optional[float] = None,
+    ) -> Self:
+        base_model_scores = {k: self.model_graph.nodes[k]["val_score"] for k in self.model_graph.nodes}
+        model_names = list(base_model_scores.keys())
+
+        if not self._can_fit_ensemble(time_limit, len(model_names)):
+            return self
+
+        logger.info(f"Fitting {len(self.ensemble_hyperparameters)} ensemble(s).")
+
+        # get target and base model prediction data for ensemble training
+        data_per_window = self._get_validation_windows(train_data=train_data, val_data=val_data)
+        predictions_per_window = self._get_base_model_predictions(model_names)
+
+        for ensemble_name, ensemble_hp_dict in self.ensemble_hyperparameters.items():
+            try:
+                time_start = time.monotonic()
+                ensemble_class = get_ensemble_class(ensemble_name)
+                ensemble = ensemble_class(
+                    eval_metric=self.eval_metric,
+                    target=self.target,
+                    prediction_length=self.prediction_length,
+                    path=self.path,
+                    freq=data_per_window[0].freq,
+                    quantile_levels=self.quantile_levels,
+                    hyperparameters=ensemble_hp_dict,
+                )
+                # update name to prevent name collisions
+                ensemble.name = self._get_ensemble_model_name(ensemble.name)
+
+                with warning_filter():
+                    ensemble.fit(
+                        predictions_per_window=predictions_per_window,
+                        data_per_window=data_per_window,
+                        model_scores=base_model_scores,
+                        time_limit=time_limit,
+                    )
+                ensemble.fit_time = time.monotonic() - time_start
+
+                score_per_fold = []
+                for window_idx, data in enumerate(data_per_window):
+                    predictions = ensemble.predict(
+                        {n: predictions_per_window[n][window_idx] for n in ensemble.model_names}
+                    )
+                    score_per_fold.append(self.eval_metric.score(data, predictions, self.target))
+                ensemble.val_score = float(np.mean(score_per_fold, dtype=np.float64))
+
+                # TODO: add ensemble's own time to predict_time
+                ensemble.predict_time = self._calculate_base_models_predict_time(ensemble.model_names)
+
+                log_scores_and_times(
+                    ensemble.val_score,
+                    ensemble.fit_time,
+                    ensemble.predict_time,
+                    eval_metric_name=self.eval_metric.name_with_sign,
+                )
+
+                self._add_model(ensemble, base_models=ensemble.model_names)
+
+                # Save the ensemble model to disk
+                ensemble.save()
+            except Exception as err:  # noqa
+                logger.error(
+                    f"\tWarning: Exception caused {ensemble_name} to fail during training... Skipping this model."
+                )
+                logger.error(f"\t{err}")
+                logger.debug(traceback.format_exc())
+
+        return self
+
+    def _add_model(self, model, base_models: list[str]):
+        self.model_graph.add_node(
+            model.name,
+            path=os.path.relpath(model.path, self.path).split(os.sep),
+            type=type(model),
+            fit_time=model.fit_time,
+            predict_time=model.predict_time,
+            val_score=model.val_score,
+        )
+        for base_model in base_models:
+            self.model_graph.add_edge(base_model, model.name)
+
+    def _can_fit_ensemble(
+        self,
+        time_limit: Optional[float],
+        num_models_available_for_ensemble: int,
+    ) -> bool:
+        if time_limit is not None and time_limit <= 0:
+            logger.info(f"Not fitting ensemble due to lack of time remaining. Time left: {time_limit:.1f} seconds")
+            return False
+
+        if num_models_available_for_ensemble <= 1:
+            logger.info(
+                "Not fitting ensemble as "
+                + (
+                    "no models were successfully trained."
+                    if not num_models_available_for_ensemble
+                    else "only 1 model was trained."
+                )
+            )
+            return False
+
+        return True
+
+    def _get_validation_windows(
+        self, train_data: TimeSeriesDataFrame, val_data: Optional[TimeSeriesDataFrame]
+    ) -> list[TimeSeriesDataFrame]:
+        # TODO: update for window/stack-layer logic and refit logic
+        if val_data is None:
+            return [val_fold for _, val_fold in self.window_splitter.split(train_data)]
+        else:
+            return [val_data]
+
+    def _get_ensemble_model_name(self, name: str) -> str:
+        """Revise name for an ensemble model, ensuring we don't have name collisions"""
+        base_name = name
+        increment = 1
+        while name in self.banned_model_names:
+            increment += 1
+            name = f"{base_name}_{increment}"
+        return name
+
+    def _get_base_model_predictions(self, model_names: list[str]) -> dict[str, list[TimeSeriesDataFrame]]:
+        """Get base model predictions for ensemble training / inference."""
+        # TODO: update for window/stack-layer logic and refit logic
+        predictions_per_window = {}
+
+        for model_name in model_names:
+            model_attrs = self.model_graph.nodes[model_name]
+
+            model_path = os.path.join(self.path, *model_attrs["path"])
+            model_type = model_attrs["type"]
+
+            predictions_per_window[model_name] = model_type.load_oof_predictions(path=model_path)
+
+        return predictions_per_window
+
+    def _calculate_base_models_predict_time(self, model_names: list[str]) -> float:
+        """Calculate ensemble predict time as sum of base model predict times."""
+        return sum(self.model_graph.nodes[name]["predict_time"] for name in model_names)
+
+
+def validate_ensemble_hyperparameters(hyperparameters) -> dict:
+    """Validate ensemble hyperparameters dict."""
+    if not isinstance(hyperparameters, dict):
+        raise ValueError(f"ensemble_hyperparameters must be dict, got {type(hyperparameters)}")
+
+    # Validate all ensemble names are known
+    for ensemble_name, ensemble_hyperparameters in hyperparameters.items():
+        get_ensemble_class(ensemble_name)  # Will raise if unknown
+        assert isinstance(ensemble_hyperparameters, dict)
+    return hyperparameters