TimeSeriesPredictor.fit¶

Fit probabilistic forecasting models to the given time series dataset.

Parameters:

train_data (TimeSeriesDataFrame | pd.DataFrame | Path | str) –
Training data in the TimeSeriesDataFrame format.

Time series with length <= (num_val_windows + 1) * prediction_length will be ignored during training. See num_val_windows for details.

If known_covariates_names were specified when creating the predictor, train_data must include the columns listed in known_covariates_names with the covariates values aligned with the target time series.

Columns of train_data except target and those listed in known_covariates_names will be interpreted as past_covariates - covariates that are known only in the past.

If train_data contains covariates or static features, they will be interpreted as follows:
- columns with int, bool and float dtypes are interpreted as continuous (real-valued) features
- columns with object, str and category dtypes are as interpreted as categorical features
- columns with other dtypes are ignored
To ensure that the column type is interpreted correctly, please convert it to one of the above dtypes. For example, to ensure that column “store_id” with dtype int is interpreted as a category, change its dtype to category:
```
data.static_features["store_id"] = data.static_features["store_id"].astype("category")
```
If provided data is a pandas.DataFrame, AutoGluon will attempt to convert it to a TimeSeriesDataFrame. If a str or a Path is provided, AutoGluon will attempt to load this file.
tuning_data (TimeSeriesDataFrame | pd.DataFrame | Path | str, optional) –
Data reserved for model selection and hyperparameter tuning, rather than training individual models. Also used to compute the validation scores. Note that only the last prediction_length time steps of each time series are used for computing the validation score.

If tuning_data is provided, multi-window backtesting on training data will be disabled, the num_val_windows will be set to 0, and refit_full will be set to False.

Leaving this argument empty and letting AutoGluon automatically generate the validation set from train_data is a good default.

The names and dtypes of columns and static features in tuning_data must match the train_data.

If provided data is a pandas.DataFrame, AutoGluon will attempt to convert it to a TimeSeriesDataFrame. If a str or a Path is provided, AutoGluon will attempt to load this file.
time_limit (int, optional) – Approximately how long fit() will run (wall-clock time in seconds). If not specified, fit() will run until all models have completed training.
presets (str, optional) –
Optional preset configurations for various arguments in fit().

Can significantly impact predictive accuracy, memory footprint, inference latency of trained models, and various other properties of the returned predictor. It is recommended to specify presets and avoid specifying most other fit() arguments or model hyperparameters prior to becoming familiar with AutoGluon. For example, set presets="high_quality" to get a high-accuracy predictor, or set presets="fast_training" to quickly get the results. Any user-specified arguments in fit() will override the values used by presets.

Available presets:
- "fast_training": Simple statistical and tree-based ML models. These models are fast to train but may not be very accurate.
- "medium_quality": Same models as above, plus deep learning models TemporalFusionTransformer and Chronos-2 (small). Produces good forecasts with reasonable training time.
- "high_quality": A mix of multiple DL, ML and statistical forecasting models available in AutoGluon that offers the best forecast accuracy. Much more accurate than medium_quality, but takes longer to train.
- "best_quality": Same models as in "high_quality", but performs validation with multiple backtests. Usually better than high_quality, but takes even longer to train.
Available presets with the Chronos-2 and Chronos-Bolt models:
- "chronos2": Chronos-2 base model for zero-shot forecasting.
- "chronos2_small": Smaller Chronos-2 model for faster zero-shot forecasting with lower memory footprint.
- "chronos2_ensemble": Ensemble combining zero-shot Chronos-2 base model with fine-tuned Chronos-2 small model for improved accuracy.
- "bolt_{model_size}": where model size is one of tiny,mini,small,base. Uses the Chronos-Bolt pretrained model for zero-shot forecasting.
See the documentation for Chronos2 and Chronos models in Forecasting Time Series - Model Zoo or see Hugging Face for more information.

Exact definitions of all presets can be found in the source code [1, 2].

If no presets are selected, user-provided values for hyperparameters will be used (defaulting to their default values specified below).
hyperparameters (str or dict, optional) –
Determines what models are trained and what hyperparameters are used by each model.

If str is passed, will use a preset hyperparameter configuration defined in autogluon/timeseries/trainer/models/presets.py. Supported values are "default", "light" and "very_light".

If dict is provided, the keys are strings or types that indicate which models to train. Each value is itself a dict containing hyperparameters for each of the trained models, or a list of such dicts. Any omitted hyperparameters not specified here will be set to default. For example:
```
predictor.fit(
    ...
    hyperparameters={
        "DeepAR": {},
        "Theta": [
            {"decomposition_type": "additive"},
            {"seasonal_period": 1},
        ],
    }
)
```
The above example will train three models:
- DeepAR with default hyperparameters
- Theta with additive seasonal decomposition (all other parameters set to their defaults)
- Theta with seasonality disabled (all other parameters set to their defaults)
Full list of available models and their hyperparameters is provided in Forecasting Time Series - Model Zoo.

The hyperparameters for each model can be fixed values (as shown above), or search spaces over which hyperparameter optimization is performed. A search space should only be provided when hyperparameter_tune_kwargs is given (i.e., hyperparameter-tuning is utilized). For example:
```
from autogluon.common import space

predictor.fit(
    ...
    hyperparameters={
        "DeepAR": {
            "hidden_size": space.Int(20, 100),
            "dropout_rate": space.Categorical(0.1, 0.3),
        },
    },
    hyperparameter_tune_kwargs="auto",
)
```
In the above example, multiple versions of the DeepAR model with different values of the parameters “hidden_size” and “dropout_rate” will be trained.
hyperparameter_tune_kwargs (str or dict, optional) –
Hyperparameter tuning strategy and kwargs (for example, how many HPO trials to run). If None, then hyperparameter tuning will not be performed.

If type is str, then this argument specifies a preset. Valid preset values:
- ”auto”: Performs HPO via bayesian optimization search on GluonTS-backed neural forecasting models and random search on other models using local scheduler.
- ”random”: Performs HPO via random search.
You can also provide a dict to specify searchers and schedulers Valid keys:
- ”num_trials”: How many HPO trials to run
- ”scheduler”: Which scheduler to use. Valid values:
  - ”local”: Local scheduler that schedules trials FIFO
- ”searcher”: Which searching algorithm to use. Valid values:
  - ”local_random”: Uses the “random” searcher
  - ”random”: Perform random search
  - ”bayes”: Perform HPO with HyperOpt on GluonTS-backed models via Ray tune. Perform random search on other models.
  - ”auto”: alias for “bayes”
To enable HyperOpt, install the corresponding extra with pip install "autogluon.timeseries[ray]".

The “scheduler” and “searcher” key are required when providing a dict.

Example:
```
predictor.fit(
    ...
    hyperparameter_tune_kwargs={
        "num_trials": 5,
        "searcher": "auto",
        "scheduler": "local",
    },
)
```
excluded_model_types (list[str], optional) –
Banned subset of model types to avoid training during fit(), even if present in hyperparameters. For example, the following code will train all models included in the high_quality presets except DeepAR:
```
predictor.fit(
    ...,
    presets="high_quality",
    excluded_model_types=["DeepAR"],
)
```
ensemble_hyperparameters (dict or list of dict, optional) –
Hyperparameters for ensemble models. Can be a single dict for one ensemble layer, or a list of dicts for multiple ensemble layers (multi-layer stacking).

For single-layer ensembling (default):
```
predictor.fit(
    ...,
    ensemble_hyperparameters={"WeightedEnsemble": {"ensemble_size": 10}},
)
```
For multi-layer ensembling, provide a list where each element configures one ensemble layer:
```
predictor.fit(
    ...,
    num_val_windows=(2, 3),
    ensemble_hyperparameters=[
        {"WeightedEnsemble": {"ensemble_size": 5}, "SimpleAverageEnsemble": {}},  # Layer 1
        {"PerformanceWeightedEnsemble": {}},       # Layer 2
    ],
)
```
When using multi-layer ensembling, num_val_windows must be a tuple of integers, and len(ensemble_hyperparameters) must match len(num_val_windows).
num_val_windows (int | tuple[int, ...] | "auto", default = 1) –
Number of backtests done on train_data for each trained model to estimate the validation performance. This parameter is also used to control multi-layer ensembling.

If set to "auto", the value will be determined automatically based on dataset properties (number of time series and median time series length).

Increasing this parameter increases the training time roughly by a factor of num_val_windows // refit_every_n_windows. See refit_every_n_windows and val_step_size for details.

For example, for prediction_length=2, num_val_windows=3 and val_step_size=1 the folds are:
```
|-------------------|
| x x x x x y y - - |
| x x x x x x y y - |
| x x x x x x x y y |
```
where x are the train time steps and y are the validation time steps.

This parameter can also be used to control how many of the backtesting windows are reserved for training multiple layers of ensemble models. By default, AutoGluon-TimeSeries uses only a single layer of ensembles trained on the backtest windows specified by the num_val_windows parameter. However, the ensemble_hyperparameters argument can be used to specify multiple layers of ensembles. In this case, a tuple of integers can be provided in num_val_windows to control how many of the backtesting windows will be used to train which ensemble layers.

For example, if len(ensemble_hyperparameters) == 2, a 2-tuple num_val_windows=(2, 3) is analogous to num_val_windows=5, except the first layer of ensemble models will be trained on the first two backtest windows, and the second layer will be trained on the latter three. Validation scores of all models will be computed on the last three windows.

If len(ensemble_hyperparameters) == 1, then num_val_windows=(5,) has the same effect as num_val_windows=5.

If tuning_data is provided and len(ensemble_hyperparameters) == 1, then this parameter is ignored. Validation and ensemble training will be performed on tuning_data.

If tuning_data is provided and len(ensemble_hyperparameters) > 1, then this method expects that len(num_val_windows) > 1. In this case, the last element of num_val_windows will be ignored. The last layer of ensemble training will be performed on tuning_data. Validation scores will likewise be computed on tuning_data.
val_step_size (int or None, default = None) –
Step size between consecutive validation windows. If set to None, defaults to prediction_length provided when creating the predictor.

If tuning_data is provided and len(ensemble_hyperparameters) == 1, then this parameter is ignored.
refit_every_n_windows (int | None | "auto", default = 1) –
When performing cross validation, each model will be retrained every refit_every_n_windows validation windows, where the number of validation windows is specified by num_val_windows. Note that in the default setting where num_val_windows=1, this argument has no effect.

If set to "auto", the value will be determined automatically based on num_val_windows.

If set to None, models will only be fit once for the first (oldest) validation window. By default, refit_every_n_windows=1, i.e., all models will be refit for each validation window.
refit_full (bool, default = False) – If True, after training is complete, AutoGluon will attempt to re-train all models using all of training data (including the data initially reserved for validation). This argument has no effect if tuning_data is provided.
enable_ensemble (bool, default = True) – If True, the TimeSeriesPredictor will fit a simple weighted ensemble on top of the models specified via hyperparameters.
skip_model_selection (bool, default = False) – If True, predictor will not compute the validation score. For example, this argument is useful if we want to use the predictor as a wrapper for a single pre-trained model. If set to True, then the hyperparameters dict must contain exactly one model without hyperparameter search spaces or an exception will be raised.
random_seed (int or None, default = 123) – If provided, fixes the seed of the random number generator for all models. This guarantees reproducible results for most models (except those trained on GPU because of the non-determinism of GPU operations).
verbosity (int, optional) – If provided, overrides the verbosity value used when creating the TimeSeriesPredictor. See documentation for TimeSeriesPredictor for more details.