.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "tutorials/time_series_forecasting.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_tutorials_time_series_forecasting.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_tutorials_time_series_forecasting.py:


Time series forecasting
=======================

.. GENERATED FROM PYTHON SOURCE LINES 7-14

This tutorial shows how to do zero-shot univariate forecasting with
:class:`tabicl.TabICLForecaster`.
Make sure the forecast dependencies are installed:

.. code-block:: bash

   pip install tabicl[forecast]

.. GENERATED FROM PYTHON SOURCE LINES 17-36

Time series forecasting as tabular regression
---------------------------------------------

:class:`tabicl.TabICLForecaster` is inspired by
`TabPFN-TS <https://arxiv.org/abs/2501.02945v3>`__.

The forecaster wraps :class:`tabicl.TabICLRegressor` and turns forecasting
into a tabular regression problem:

- each row is one timestamp,
- the target column is the series value,
- time-aware features are added automatically (index, calendar, seasonality).

.. note::

   Compared with :class:`tabicl.TabICLClassifier` and
   :class:`tabicl.TabICLRegressor`, the forecasting interface is newer and has
   not yet been evaluated on a large public benchmark. We may later provide
   evaluations and enhancements for time series forecasting.

.. GENERATED FROM PYTHON SOURCE LINES 38-44

.. code-block:: Python


    import numpy as np
    import pandas as pd
    from tabicl import TabICLForecaster
    from tabicl.forecast import plot_forecast








.. GENERATED FROM PYTHON SOURCE LINES 45-53

Build a synthetic univariate series
-----------------------------------

We create a daily series that mixes a linear trend, a weekly seasonality,
an annual seasonality, and Gaussian noise.

This makes the task intuitive: the model should extrapolate trend and recurring
patterns into the future.

.. GENERATED FROM PYTHON SOURCE LINES 53-70

.. code-block:: Python


    rng = np.random.default_rng(0)
    n_timesteps = 365 * 2  # two years of daily observations
    dates = pd.date_range(start="2022-01-01", periods=n_timesteps, freq="D")
    t = np.arange(n_timesteps)

    trend = 0.05 * t
    weekly_season = 5.0 * np.sin(2 * np.pi * t / 7)
    annual_season = 10.0 * np.sin(2 * np.pi * t / 365)
    noise = rng.normal(scale=1.5, size=n_timesteps)

    target = trend + weekly_season + annual_season + noise

    # For a single time series, ``timestamp`` and ``target`` are sufficient.
    df = pd.DataFrame({"timestamp": dates, "target": target})
    df.head()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <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>timestamp</th>
          <th>target</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>2022-01-01</td>
          <td>0.188595</td>
        </tr>
        <tr>
          <th>1</th>
          <td>2022-01-02</td>
          <td>3.933134</td>
        </tr>
        <tr>
          <th>2</th>
          <td>2022-01-03</td>
          <td>6.279490</td>
        </tr>
        <tr>
          <th>3</th>
          <td>2022-01-04</td>
          <td>2.992966</td>
        </tr>
        <tr>
          <th>4</th>
          <td>2022-01-05</td>
          <td>-2.084898</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 71-78

This DataFrame follows the input format required by
:meth:`tabicl.TabICLForecaster.predict_df`:

- required columns: ``timestamp``, ``target``
- optional column: ``item_id`` (for multiple series)
- use ``prediction_length`` for regular horizons, or ``future_df`` when you
  already know future timestamps/covariates

.. GENERATED FROM PYTHON SOURCE LINES 81-88

Define forecast horizon and hold-out period
-------------------------------------------

We keep the last ``prediction_length`` points as a pseudo-future set.

- ``context_df`` is the observed history provided to the forecaster.
- ``test_df`` is only used for visual comparison.

.. GENERATED FROM PYTHON SOURCE LINES 88-93

.. code-block:: Python


    prediction_length = 30
    context_df = df.iloc[:-prediction_length]
    test_df = df.iloc[-prediction_length:]








.. GENERATED FROM PYTHON SOURCE LINES 94-99

Forecast with TabICLForecaster
------------------------------

:meth:`tabicl.TabICLForecaster.predict_df` returns one row per future
timestamp, with a point forecast and quantile columns for uncertainty.

.. GENERATED FROM PYTHON SOURCE LINES 99-104

.. code-block:: Python


    forecaster = TabICLForecaster()
    pred_df = forecaster.predict_df(context_df, prediction_length=prediction_length)






.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    Predicting time series:   0%|          | 0/1 [00:00<?, ?it/s]
    Predicting time series: 100%|██████████| 1/1 [00:05<00:00,  5.89s/it]
    Predicting time series: 100%|██████████| 1/1 [00:05<00:00,  5.89s/it]




.. GENERATED FROM PYTHON SOURCE LINES 105-107

Plot context, forecast, and held-out truth
------------------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 107-110

.. code-block:: Python


    fig, axes = plot_forecast(context_df=context_df, pred_df=pred_df, test_df=test_df)




.. image-sg:: /tutorials/images/sphx_glr_time_series_forecasting_001.png
   :alt: Item ID: 0
   :srcset: /tutorials/images/sphx_glr_time_series_forecasting_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 111-114

A good forecast should continue the upward trend and recover the recurring
seasonal pattern visible in the held-out future values, which the
``TabICLForecaster`` does successfully in this example.


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 6.678 seconds)


.. _sphx_glr_download_tutorials_time_series_forecasting.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: time_series_forecasting.ipynb <time_series_forecasting.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: time_series_forecasting.py <time_series_forecasting.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: time_series_forecasting.zip <time_series_forecasting.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_