AutoGluon Time Series - Forecasting Quick Start

Open In Colab Open In SageMaker Studio Lab

Via a simple fit() call, AutoGluon can train and tune

  • simple forecasting models (e.g., ARIMA, ETS, Theta),

  • powerful deep learning models (e.g., DeepAR, Temporal Fusion Transformer),

  • tree-based models (e.g., LightGBM),

  • an ensemble that combines predictions of other models

to produce multi-step ahead probabilistic forecasts for univariate time series data.

This tutorial demonstrates how to quickly start using AutoGluon to generate hourly forecasts for the M4 forecasting competition dataset.

Loading time series data as a TimeSeriesDataFrame

First, we import some required modules

import pandas as pd
from autogluon.timeseries import TimeSeriesDataFrame, TimeSeriesPredictor

To use autogluon.timeseries, we will only need the following two classes:

  • TimeSeriesDataFrame stores a dataset consisting of multiple time series.

  • TimeSeriesPredictor takes care of fitting, tuning and selecting the best forecasting models, as well as generating new forecasts.

We load a subset of the M4 hourly dataset as a pandas.DataFrame

df = pd.read_csv("https://autogluon.s3.amazonaws.com/datasets/timeseries/m4_hourly_subset/train.csv")
df.head()
item_id timestamp target
0 H1 1750-01-01 00:00:00 605.0
1 H1 1750-01-01 01:00:00 586.0
2 H1 1750-01-01 02:00:00 586.0
3 H1 1750-01-01 03:00:00 559.0
4 H1 1750-01-01 04:00:00 511.0

AutoGluon expects time series data in long format. Each row of the dataframe contains a single observation (timestep) of a single time series represented by

  • unique ID of the time series ("item_id") as int or str

  • timestamp of the observation ("timestamp") as a pandas.Timestamp or compatible format

  • numeric value of the time series ("target")

The raw dataset should always follow this format with at least three columns for unique ID, timestamp, and target value, but the names of these columns can be arbitrary. It is important, however, that we provide the names of the columns when constructing a TimeSeriesDataFrame that is used by AutoGluon. AutoGluon will raise an exception if the data doesn’t match the expected format.

train_data = TimeSeriesDataFrame.from_data_frame(
    df,
    id_column="item_id",
    timestamp_column="timestamp"
)
train_data.head()
target
item_id timestamp
H1 1750-01-01 00:00:00 605.0
1750-01-01 01:00:00 586.0
1750-01-01 02:00:00 586.0
1750-01-01 03:00:00 559.0
1750-01-01 04:00:00 511.0

We refer to each individual time series stored in a TimeSeriesDataFrame as an item. For example, items might correspond to different products in demand forecasting, or to different stocks in financial datasets. This setting is also referred to as a panel of time series. Note that this is not the same as multivariate forecasting — AutoGluon generates forecasts for each time series individually, without modeling interactions between different items (time series).

TimeSeriesDataFrame inherits from pandas.DataFrame, so all attributes and methods of pandas.DataFrame are available in a TimeSeriesDataFrame. It also provides other utility functions, such as loaders for different data formats (see TimeSeriesDataFrame for details).

Training time series models with TimeSeriesPredictor.fit

To forecast future values of the time series, we need to create a TimeSeriesPredictor object.

Models in autogluon.timeseries forecast time series multiple steps into the future. We choose the number of these steps — the prediction length (also known as the forecast horizon) — depending on our task. For example, our dataset contains time series measured at hourly frequency, so we set prediction_length = 48 to train models that forecast up to 48 hours into the future.

We instruct AutoGluon to save trained models in the folder ./autogluon-m4-hourly. We also specify that AutoGluon should rank models according to mean absolute scaled error (MASE), and that data that we want to forecast is stored in the column "target" of the TimeSeriesDataFrame.

predictor = TimeSeriesPredictor(
    prediction_length=48,
    path="autogluon-m4-hourly",
    target="target",
    eval_metric="MASE",
)

predictor.fit(
    train_data,
    presets="medium_quality",
    time_limit=600,
)

Beginning AutoGluon training... Time limit = 600s
AutoGluon will save models to '/home/ci/autogluon/docs/tutorials/timeseries/autogluon-m4-hourly'
=================== System Info ===================
AutoGluon Version:  1.4.1b20251214
Python Version:     3.12.10
Operating System:   Linux
Platform Machine:   x86_64
Platform Version:   #1 SMP Wed Mar 12 14:53:59 UTC 2025
CPU Count:          8
Pytorch Version:    2.9.1+cu128
CUDA Version:       12.8
GPU Memory:         GPU 0: 14.57/14.57 GB
Total GPU Memory:   Free: 14.57 GB, Allocated: 0.00 GB, Total: 14.57 GB
GPU Count:          1
Memory Avail:       28.68 GB / 30.95 GB (92.7%)
Disk Space Avail:   204.34 GB / 255.99 GB (79.8%)
===================================================
Setting presets to: medium_quality

Fitting with arguments:
{'enable_ensemble': True,
 'eval_metric': MASE,
 'hyperparameters': 'light',
 'known_covariates_names': [],
 'num_val_windows': 1,
 'prediction_length': 48,
 'quantile_levels': [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9],
 'random_seed': 123,
 'refit_every_n_windows': 1,
 'refit_full': False,
 'skip_model_selection': False,
 'target': 'target',
 'time_limit': 600,
 'verbosity': 2}
Inferred time series frequency: 'h'
Provided train_data has 148060 rows, 200 time series. Median time series length is 700 (min=700, max=960).

Provided data contains following columns:
	target: 'target'

AutoGluon will gauge predictive performance using evaluation metric: 'MASE'
	This metric's sign has been flipped to adhere to being higher_is_better. The metric score can be multiplied by -1 to get the metric value.
===================================================

Starting training. Start time is 2025-12-14 18:05:25
Models that will be trained: ['Naive', 'SeasonalNaive', 'RecursiveTabular', 'DirectTabular', 'ETS', 'Theta', 'Chronos[bolt_small]', 'TemporalFusionTransformer']
Training timeseries model Naive. Training for up to 66.4s of the 597.8s of remaining time.
	-6.6629       = Validation score (-MASE)
	0.06    s     = Training runtime
	2.20    s     = Validation (prediction) runtime
Training timeseries model SeasonalNaive. Training for up to 74.4s of the 595.5s of remaining time.
	-1.2169       = Validation score (-MASE)
	0.06    s     = Training runtime
	0.17    s     = Validation (prediction) runtime
Training timeseries model RecursiveTabular. Training for up to 85.0s of the 595.3s of remaining time.
	-0.9339       = Validation score (-MASE)
	10.27   s     = Training runtime
	0.52    s     = Validation (prediction) runtime
Training timeseries model DirectTabular. Training for up to 97.4s of the 584.5s of remaining time.
	-1.3729       = Validation score (-MASE)
	4.63    s     = Training runtime
	0.36    s     = Validation (prediction) runtime
Training timeseries model ETS. Training for up to 115.9s of the 579.5s of remaining time.
	-1.9661       = Validation score (-MASE)
	0.06    s     = Training runtime
	26.84   s     = Validation (prediction) runtime
Training timeseries model Theta. Training for up to 138.1s of the 552.6s of remaining time.
	-2.1426       = Validation score (-MASE)
	0.06    s     = Training runtime
	1.62    s     = Validation (prediction) runtime
Training timeseries model Chronos[bolt_small]. Training for up to 183.6s of the 550.9s of remaining time.
	-0.8121       = Validation score (-MASE)
	2.64    s     = Training runtime
	0.94    s     = Validation (prediction) runtime
Training timeseries model TemporalFusionTransformer. Training for up to 273.6s of the 547.3s of remaining time.
	Warning: Exception caused TemporalFusionTransformer to fail during training... Skipping this model.
Traceback (most recent call last):
  File "/home/ci/autogluon/timeseries/src/autogluon/timeseries/trainer/trainer.py", line 353, in _train_and_save
    model.fit(
  File "/home/ci/autogluon/timeseries/src/autogluon/timeseries/models/abstract/abstract_timeseries_model.py", line 529, in fit
    self._fit(
  File "/home/ci/autogluon/timeseries/src/autogluon/timeseries/models/multi_window/multi_window_model.py", line 141, in _fit
    model.fit(
  File "/home/ci/autogluon/timeseries/src/autogluon/timeseries/models/abstract/abstract_timeseries_model.py", line 529, in fit
    self._fit(
  File "/home/ci/autogluon/timeseries/src/autogluon/timeseries/models/gluonts/abstract.py", line 426, in _fit
    self.gts_predictor = estimator.train(
                         ^^^^^^^^^^^^^^^^
  File "/home/ci/opt/venv/lib/python3.12/site-packages/gluonts/torch/model/estimator.py", line 246, in train
    return self.train_model(
           ^^^^^^^^^^^^^^^^^
  File "/home/ci/opt/venv/lib/python3.12/site-packages/gluonts/torch/model/estimator.py", line 209, in train_model
    trainer.fit(
  File "/home/ci/opt/venv/lib/python3.12/site-packages/lightning/pytorch/trainer/trainer.py", line 560, in fit
    call._call_and_handle_interrupt(
  File "/home/ci/opt/venv/lib/python3.12/site-packages/lightning/pytorch/trainer/call.py", line 49, in _call_and_handle_interrupt
    return trainer_fn(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ci/opt/venv/lib/python3.12/site-packages/lightning/pytorch/trainer/trainer.py", line 598, in _fit_impl
    self._run(model, ckpt_path=ckpt_path)
  File "/home/ci/opt/venv/lib/python3.12/site-packages/lightning/pytorch/trainer/trainer.py", line 987, in _run
    self.strategy.setup(self)
  File "/home/ci/opt/venv/lib/python3.12/site-packages/lightning/pytorch/strategies/strategy.py", line 155, in setup
    self.model_to_device()
  File "/home/ci/opt/venv/lib/python3.12/site-packages/lightning/pytorch/strategies/single_device.py", line 79, in model_to_device
    self.model.to(self.root_device)
  File "/home/ci/opt/venv/lib/python3.12/site-packages/lightning/fabric/utilities/device_dtype_mixin.py", line 55, in to
    return super().to(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ci/opt/venv/lib/python3.12/site-packages/torch/nn/modules/module.py", line 1371, in to
    return self._apply(convert)
           ^^^^^^^^^^^^^^^^^^^^
  File "/home/ci/opt/venv/lib/python3.12/site-packages/torch/nn/modules/module.py", line 930, in _apply
    module._apply(fn)
  File "/home/ci/opt/venv/lib/python3.12/site-packages/torch/nn/modules/module.py", line 930, in _apply
    module._apply(fn)
  File "/home/ci/opt/venv/lib/python3.12/site-packages/torch/nn/modules/module.py", line 930, in _apply
    module._apply(fn)
  File "/home/ci/opt/venv/lib/python3.12/site-packages/torch/nn/modules/rnn.py", line 291, in _apply
    self._init_flat_weights()
  File "/home/ci/opt/venv/lib/python3.12/site-packages/torch/nn/modules/rnn.py", line 215, in _init_flat_weights
    self.flatten_parameters()
  File "/home/ci/opt/venv/lib/python3.12/site-packages/torch/nn/modules/rnn.py", line 247, in flatten_parameters
    or not torch.backends.cudnn.is_acceptable(fw)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ci/opt/venv/lib/python3.12/site-packages/torch/backends/cudnn/__init__.py", line 120, in is_acceptable
    if not _init():
           ^^^^^^^
  File "/home/ci/opt/venv/lib/python3.12/site-packages/torch/backends/cudnn/__init__.py", line 74, in _init
    raise RuntimeError(
RuntimeError: cuDNN version incompatibility: PyTorch was compiled  against (9, 8, 0) but found runtime version (9, 7, 1). PyTorch already comes bundled with cuDNN. One option to resolving this error is to ensure PyTorch can find the bundled cuDNN. one possibility is that there is a conflicting cuDNN in LD_LIBRARY_PATH.
Fitting 1 ensemble(s), in 1 layers.
Training ensemble model WeightedEnsemble. Training for up to 546.4s.
	Ensemble weights: {'Chronos[bolt_small]': 0.74, 'DirectTabular': 0.05, 'ETS': 0.02, 'RecursiveTabular': 0.19}
	-0.7888       = Validation score (-MASE)
	0.87    s     = Training runtime
	28.67   s     = Validation (prediction) runtime
Training complete. Models trained: ['Naive', 'SeasonalNaive', 'RecursiveTabular', 'DirectTabular', 'ETS', 'Theta', 'Chronos[bolt_small]', 'WeightedEnsemble']
Total runtime: 52.87 s
Best model: WeightedEnsemble
Best model score: -0.7888

<autogluon.timeseries.predictor.TimeSeriesPredictor at 0x7fb0c01ebce0>

Here we used the "medium_quality" presets and limited the training time to 10 minutes (600 seconds). The presets define which models AutoGluon will try to fit. For medium_quality presets, these are simple baselines (Naive, SeasonalNaive), statistical models (ETS, Theta), tree-based models based on LightGBM (RecursiveTabular, DirectTabular), a deep learning model TemporalFusionTransformer, and a weighted ensemble combining these. Other available presets for TimeSeriesPredictor are "fast_training", "high_quality" and "best_quality". Higher quality presets will usually produce more accurate forecasts but take longer to train.

Inside fit(), AutoGluon will train as many models as possible within the given time limit. Trained models are then ranked based on their performance on an internal validation set. By default, this validation set is constructed by holding out the last prediction_length timesteps of each time series in train_data.

Generating forecasts with TimeSeriesPredictor.predict

We can now use the fitted TimeSeriesPredictor to forecast the future time series values. By default, AutoGluon will make forecasts using the model that had the best score on the internal validation set. The forecast always includes predictions for the next prediction_length timesteps, starting from the end of each time series in train_data.

predictions = predictor.predict(train_data)
predictions.head()

Model not specified in predict, will default to the model with the best validation score: WeightedEnsemble
mean 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9
item_id timestamp
H1 1750-01-30 04:00:00 622.776243 598.522254 607.131623 613.369898 618.187182 622.776243 627.502724 632.165406 637.652368 645.545978
1750-01-30 05:00:00 562.953777 536.512925 546.291844 552.745020 558.059900 562.953777 567.493558 572.442594 578.339679 587.106848
1750-01-30 06:00:00 521.652610 493.585528 503.476584 510.784037 516.486087 521.652610 526.961223 532.472752 538.844688 548.472958
1750-01-30 07:00:00 490.085221 460.345643 470.777014 478.260260 484.488636 490.085221 496.041058 502.186334 509.182795 520.266845
1750-01-30 08:00:00 465.629743 434.152203 444.763806 452.625721 459.618612 465.629743 471.570256 477.938392 485.694380 496.906966

AutoGluon produces a probabilistic forecast: in addition to predicting the mean (expected value) of the time series in the future, models also provide the quantiles of the forecast distribution. The quantile forecasts give us an idea about the range of possible outcomes. For example, if the "0.1" quantile is equal to 500.0, it means that the model predicts a 10% chance that the target value will be below 500.0.

We will now visualize the forecast and the actually observed values for one of the time series in the dataset. We plot the mean forecast, as well as the 10% and 90% quantiles to show the range of potential outcomes.

import matplotlib.pyplot as plt

# TimeSeriesDataFrame can also be loaded directly from a file
test_data = TimeSeriesDataFrame.from_path("https://autogluon.s3.amazonaws.com/datasets/timeseries/m4_hourly_subset/test.csv")

# Plot 4 randomly chosen time series and the respective forecasts
predictor.plot(test_data, predictions, quantile_levels=[0.1, 0.9], max_history_length=200, max_num_item_ids=4);

Loaded data from: https://autogluon.s3.amazonaws.com/datasets/timeseries/m4_hourly_subset/test.csv | Columns = 3 / 3 | Rows = 157660 -> 157660
../../_images/52a32550aa39465803b450e89fcf4884c1cec3a5d32a765c061d4a28e44dcb27.png

Evaluating the performance of different models

We can view the performance of each model AutoGluon has trained via the leaderboard() method. We provide the test data set to the leaderboard function to see how well our fitted models are doing on the unseen test data. The leaderboard also includes the validation scores computed on the internal validation dataset.

Note the test data includes both the forecast horizon (last prediction_length values of each time series) as well as the historical data (all except the last prediction_last values).

In AutoGluon leaderboards, higher scores always correspond to better predictive performance. Therefore our MASE scores are multiplied by -1, such that higher “negative MASE”s correspond to more accurate forecasts.

# The test score is computed using the last
# prediction_length=48 timesteps of each time series in test_data
predictor.leaderboard(test_data)

Additional data provided, testing on additional data. Resulting leaderboard will be sorted according to test score (`score_test`).
model score_test score_val pred_time_test pred_time_val fit_time_marginal fit_order
0 WeightedEnsemble -0.697231 -0.788793 32.561212 28.668973 0.874390 8
1 Chronos[bolt_small] -0.725739 -0.812070 0.448398 0.942371 2.637311 7
2 RecursiveTabular -0.862797 -0.933874 0.526033 0.519142 10.273721 3
3 SeasonalNaive -1.022854 -1.216909 0.154294 0.172819 0.056324 2
4 DirectTabular -1.648202 -1.372871 0.420189 0.357539 4.631369 4
5 ETS -1.806136 -1.966098 31.159196 26.842085 0.055806 5
6 Theta -1.905367 -2.142551 1.805727 1.615263 0.055282 6
7 Naive -6.696079 -6.662942 0.151052 2.201156 0.061148 1

Summary

We used autogluon.timeseries to make probabilistic multi-step forecasts on the M4 Hourly dataset. Check out Forecasting Time Series - In Depth to learn about the advanced capabilities of AutoGluon for time series forecasting.