This guide demonstrates how to use calendar variables and special dates to improve forecast accuracy for time series data — especially useful for window-based forecasting with models like TimeGPT-1.

What are calendar variables?

Calendar variables include indicators such as month, week, day, or hour. They help a model understand time-based patterns that might not be captured in a limited historical window.

Why holidays?

Special dates (like holidays) can cause significant changes in demand or activity. Including these events in your forecasts can lead to more accurate predictions.


​
Tutorial Overview

1

1. Import Packages

Import the required libraries and initialize the Nixtla client.

import pandas as pd
from nixtla import NixtlaClient
NixtlaClient Default Initialization
nixtla_client = NixtlaClient(
    api_key='my_api_key_provided_by_nixtla'
)

You can also specify the base_url to use an Azure AI endpoint in place of Nixtla’s default.

2

2. Load Data

We use a Google Trends dataset on “chocolate” with monthly frequency:

df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/google_trend_chocolate.csv')
df['month'] = pd.to_datetime(df['month']).dt.to_period('M').dt.to_timestamp('M')

df.head()
monthchocolate
02004-01-3135
12004-02-2945
22004-03-3128
32004-04-3030
42004-05-3129
3

3. Forecast with Holidays and Special Dates

Nixtla automatically creates common date features during forecasting. Here, we explicitly include holiday indicators (for the US) in the forecast.

If you’re using an Azure AI endpoint, specify the model:

nixtla_client.forecast(..., model="azureai")

Available models:

  • timegpt-1 (default)

  • timegpt-1-long-horizon

For more information, see the Long Horizon Forecasting Tutorial.

​
Understanding the date_features Parameter

Adding these parameters often improves forecast accuracy by providing richer temporal context.


Congratulations! You have successfully integrated holiday and special date features into your time series forecasts. Use these steps as a starting point for further experimentation with advanced date features.