.. _sec_forecasting_quickstart:

Forecasting Time Series - Quick Start
=====================================


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., XGBoost, CatBoost, 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 <https://www.sciencedirect.com/science/article/pii/S0169207019301128>`__
dataset.

Loading time series data as a ``TimeSeriesDataFrame``
-----------------------------------------------------

First, we import some required modules

.. code:: python

    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 the M4 hourly dataset as a ``pandas.DataFrame``

.. code:: python

    df = pd.read_csv("https://autogluon.s3.amazonaws.com/datasets/timeseries/m4_hourly/train.csv")
    df.head()




.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }
    
        .dataframe tbody tr th {
            vertical-align: top;
        }
    
        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>item_id</th>
          <th>timestamp</th>
          <th>target</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>H1</td>
          <td>1750-01-01 00:00:00</td>
          <td>605.0</td>
        </tr>
        <tr>
          <th>1</th>
          <td>H1</td>
          <td>1750-01-01 01:00:00</td>
          <td>586.0</td>
        </tr>
        <tr>
          <th>2</th>
          <td>H1</td>
          <td>1750-01-01 02:00:00</td>
          <td>586.0</td>
        </tr>
        <tr>
          <th>3</th>
          <td>H1</td>
          <td>1750-01-01 03:00:00</td>
          <td>559.0</td>
        </tr>
        <tr>
          <th>4</th>
          <td>H1</td>
          <td>1750-01-01 04:00:00</td>
          <td>511.0</td>
        </tr>
      </tbody>
    </table>
    </div>



AutoGluon expects time series data in `long
format <https://doc.dataiku.com/dss/latest/time-series/data-formatting.html#long-format>`__.
Each row of the data frame 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.

.. code:: python

    train_data = TimeSeriesDataFrame.from_data_frame(
        df,
        id_column="item_id",
        timestamp_column="timestamp"
    )
    train_data.head()




.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }
    
        .dataframe tbody tr th {
            vertical-align: top;
        }
    
        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th></th>
          <th>target</th>
        </tr>
        <tr>
          <th>item_id</th>
          <th>timestamp</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th rowspan="5" valign="top">H1</th>
          <th>1750-01-01 00:00:00</th>
          <td>605.0</td>
        </tr>
        <tr>
          <th>1750-01-01 01:00:00</th>
          <td>586.0</td>
        </tr>
        <tr>
          <th>1750-01-01 02:00:00</th>
          <td>586.0</td>
        </tr>
        <tr>
          <th>1750-01-01 03:00:00</th>
          <td>559.0</td>
        </tr>
        <tr>
          <th>1750-01-01 04:00:00</th>
          <td>511.0</td>
        </tr>
      </tbody>
    </table>
    </div>



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 <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html>`__,
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
:class:`autogluon.timeseries.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 `symmetric mean absolute percentage error
(sMAPE) <https://en.wikipedia.org/wiki/Symmetric_mean_absolute_percentage_error>`__,
and that data that we want to forecast is stored in the column
``"target"`` of the ``TimeSeriesDataFrame``.

.. code:: python

    predictor = TimeSeriesPredictor(
        prediction_length=48,
        path="autogluon-m4-hourly",
        target="target",
        eval_metric="sMAPE",
    )
    
    predictor.fit(
        train_data,
        presets="medium_quality",
        time_limit=600,
    )


.. parsed-literal::
    :class: output

    ================ TimeSeriesPredictor ================
    TimeSeriesPredictor.fit() called
    Setting presets to: medium_quality
    Fitting with arguments:
    {'enable_ensemble': True,
     'evaluation_metric': 'sMAPE',
     'hyperparameter_tune_kwargs': None,
     'hyperparameters': 'medium_quality',
     'prediction_length': 48,
     'random_seed': None,
     'target': 'target',
     'time_limit': 600}
    Provided training data set with 353500 rows, 414 items (item = single time series). Average time series length is 853.9.
    Training artifacts will be saved to: /home/ci/autogluon/docs/_build/eval/tutorials/timeseries/autogluon-m4-hourly
    =====================================================
    AutoGluon will save models to autogluon-m4-hourly/
    AutoGluon will gauge predictive performance using evaluation metric: 'sMAPE'
    	This metric's sign has been flipped to adhere to being 'higher is better'. The reported score can be multiplied by -1 to get the metric value.
    tuning_data is None. Will use the last prediction_length = 48 time steps of each time series as a hold-out validation set.
    
    Starting training. Start time is 2023-01-18 21:24:01
    Models that will be trained: ['Naive', 'SeasonalNaive', 'ETS', 'Theta', 'ARIMA', 'AutoGluonTabular', 'DeepAR']
    Training timeseries model Naive. Training for up to 599.79s of the 599.79s of remaining time.
    	-0.4140       = Validation score (-sMAPE)
    	0.00    s     = Training runtime
    	6.12    s     = Validation (prediction) runtime
    Training timeseries model SeasonalNaive. Training for up to 593.64s of the 593.64s of remaining time.
    	-0.1457       = Validation score (-sMAPE)
    	0.00    s     = Training runtime
    	1.08    s     = Validation (prediction) runtime
    Training timeseries model ETS. Training for up to 592.54s of the 592.54s of remaining time.
    	-0.2240       = Validation score (-sMAPE)
    	0.00    s     = Training runtime
    	105.56  s     = Validation (prediction) runtime
    Training timeseries model Theta. Training for up to 486.95s of the 486.95s of remaining time.
    	-0.1904       = Validation score (-sMAPE)
    	0.00    s     = Training runtime
    	34.84   s     = Validation (prediction) runtime
    Training timeseries model ARIMA. Training for up to 452.08s of the 452.08s of remaining time.
    	-0.5228       = Validation score (-sMAPE)
    	0.00    s     = Training runtime
    	42.69   s     = Validation (prediction) runtime
    Training timeseries model AutoGluonTabular. Training for up to 409.37s of the 409.37s of remaining time.
    	-0.1030       = Validation score (-sMAPE)
    	90.26   s     = Training runtime
    	3.49    s     = Validation (prediction) runtime
    Training timeseries model DeepAR. Training for up to 315.61s of the 315.61s of remaining time.
    	-0.1138       = Validation score (-sMAPE)
    	99.26   s     = Training runtime
    	4.30    s     = Validation (prediction) runtime
    Fitting simple weighted ensemble.
    	-0.1011       = Validation score (-sMAPE)
    	11.85   s     = Training runtime
    	13.91   s     = Validation (prediction) runtime
    Training complete. Models trained: ['Naive', 'SeasonalNaive', 'ETS', 'Theta', 'ARIMA', 'AutoGluonTabular', 'DeepAR', 'WeightedEnsemble']
    Total runtime: 419.83 s
    Best model: WeightedEnsemble
    Best model score: -0.1011




.. parsed-literal::
    :class: output

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



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
(``ARIMA``, ``ETS``, ``Theta``), tree-based models XGBoost, LightGBM and
CatBoost wrapped by ``AutoGluonTabular``, a deep learning model
``DeepAR``, 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 and may
produce less computationally efficient models.

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``.

.. code:: python

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


.. parsed-literal::
    :class: output

    Model not specified in predict, will default to the model with the best validation score: WeightedEnsemble




.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }
    
        .dataframe tbody tr th {
            vertical-align: top;
        }
    
        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th></th>
          <th>mean</th>
          <th>0.1</th>
          <th>0.2</th>
          <th>0.3</th>
          <th>0.4</th>
          <th>0.5</th>
          <th>0.6</th>
          <th>0.7</th>
          <th>0.8</th>
          <th>0.9</th>
        </tr>
        <tr>
          <th>item_id</th>
          <th>timestamp</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th rowspan="5" valign="top">H1</th>
          <th>1750-01-30 04:00:00</th>
          <td>642.911412</td>
          <td>535.453927</td>
          <td>571.692302</td>
          <td>598.649978</td>
          <td>621.117859</td>
          <td>642.119557</td>
          <td>663.260708</td>
          <td>687.078364</td>
          <td>713.604737</td>
          <td>751.310133</td>
        </tr>
        <tr>
          <th>1750-01-30 05:00:00</th>
          <td>597.968943</td>
          <td>490.689915</td>
          <td>528.220328</td>
          <td>554.595857</td>
          <td>576.649496</td>
          <td>597.800791</td>
          <td>618.288862</td>
          <td>640.073321</td>
          <td>667.129288</td>
          <td>704.775007</td>
        </tr>
        <tr>
          <th>1750-01-30 06:00:00</th>
          <td>548.949019</td>
          <td>441.064859</td>
          <td>478.313623</td>
          <td>505.503912</td>
          <td>529.347558</td>
          <td>549.856055</td>
          <td>571.310818</td>
          <td>593.403731</td>
          <td>619.713321</td>
          <td>656.510418</td>
        </tr>
        <tr>
          <th>1750-01-30 07:00:00</th>
          <td>514.300286</td>
          <td>406.916431</td>
          <td>444.896585</td>
          <td>470.961884</td>
          <td>493.572538</td>
          <td>514.032509</td>
          <td>535.112155</td>
          <td>557.691101</td>
          <td>584.109138</td>
          <td>622.426738</td>
        </tr>
        <tr>
          <th>1750-01-30 08:00:00</th>
          <td>492.833387</td>
          <td>386.666305</td>
          <td>423.070487</td>
          <td>449.354325</td>
          <td>471.227917</td>
          <td>492.971662</td>
          <td>514.308013</td>
          <td>536.709299</td>
          <td>562.808666</td>
          <td>599.551333</td>
        </tr>
      </tbody>
    </table>
    </div>



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.

.. code:: python

    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/test.csv")
    
    plt.figure(figsize=(20, 3))
    
    item_id = "H3"
    y_past = train_data.loc[item_id]["target"]
    y_pred = predictions.loc[item_id]
    y_test = test_data.loc[item_id]["target"][-48:]
    
    plt.plot(y_past[-200:], label="Past time series values")
    plt.plot(y_pred["mean"], label="Mean forecast")
    plt.plot(y_test, label="Future time series values")
    
    plt.fill_between(
        y_pred.index, y_pred["0.1"], y_pred["0.9"], color="red", alpha=0.1, label=f"10%-90% confidence interval"
    )
    plt.legend();


.. parsed-literal::
    :class: output

    Loaded data from: https://autogluon.s3.amazonaws.com/datasets/timeseries/m4_hourly/test.csv | Columns = 3 / 3 | Rows = 373372 -> 373372



.. figure:: output_forecasting-quickstart_a33e23_11_1.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.

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

.. code:: python

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


.. parsed-literal::
    :class: output

    Additional data provided, testing on additional data. Resulting leaderboard will be sorted according to test score (`score_test`).




.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }
    
        .dataframe tbody tr th {
            vertical-align: top;
        }
    
        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>model</th>
          <th>score_test</th>
          <th>score_val</th>
          <th>pred_time_test</th>
          <th>pred_time_val</th>
          <th>fit_time_marginal</th>
          <th>fit_order</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>WeightedEnsemble</td>
          <td>-0.093424</td>
          <td>-0.101087</td>
          <td>19.487990</td>
          <td>13.907964</td>
          <td>11.852141</td>
          <td>8</td>
        </tr>
        <tr>
          <th>1</th>
          <td>AutoGluonTabular</td>
          <td>-0.095085</td>
          <td>-0.102993</td>
          <td>3.503335</td>
          <td>3.487810</td>
          <td>90.261163</td>
          <td>6</td>
        </tr>
        <tr>
          <th>2</th>
          <td>DeepAR</td>
          <td>-0.108422</td>
          <td>-0.113795</td>
          <td>15.480091</td>
          <td>4.296372</td>
          <td>99.255556</td>
          <td>7</td>
        </tr>
        <tr>
          <th>3</th>
          <td>SeasonalNaive</td>
          <td>-0.139123</td>
          <td>-0.145701</td>
          <td>0.911763</td>
          <td>1.075734</td>
          <td>0.002818</td>
          <td>2</td>
        </tr>
        <tr>
          <th>4</th>
          <td>Theta</td>
          <td>-0.181368</td>
          <td>-0.190419</td>
          <td>36.771878</td>
          <td>34.843445</td>
          <td>0.001481</td>
          <td>4</td>
        </tr>
        <tr>
          <th>5</th>
          <td>ETS</td>
          <td>-0.210418</td>
          <td>-0.224037</td>
          <td>114.481893</td>
          <td>105.563916</td>
          <td>0.001496</td>
          <td>3</td>
        </tr>
        <tr>
          <th>6</th>
          <td>Naive</td>
          <td>-0.430030</td>
          <td>-0.413986</td>
          <td>0.930550</td>
          <td>6.123782</td>
          <td>0.003674</td>
          <td>1</td>
        </tr>
        <tr>
          <th>7</th>
          <td>ARIMA</td>
          <td>-0.532440</td>
          <td>-0.522781</td>
          <td>45.204858</td>
          <td>42.690477</td>
          <td>0.001531</td>
          <td>5</td>
        </tr>
      </tbody>
    </table>
    </div>



Summary
-------

We used ``autogluon.timeseries`` to make probabilistic multi-step
forecasts on the M4 Hourly dataset. Check out
:ref:`sec_forecasting_indepth` to learn about the advanced
capabilities of AutoGluon for time series forecasting.