Date features are an essential part of time series analysis. This document introduces helpful classes (CountryHolidays and SpecialDates) for generating holiday flags, custom date markers, and adding them to TimeGPT.

​
Overview

CountryHolidays
Easily attach holiday flags for multiple countries based on a list of countries.

SpecialDates
Add flags for custom events or significant dates you define.

These classes help you enrich your time series datasets with relevant date-based signals. Use them alongside standard data preprocessing techniques to enhance your model’s understanding of seasonality and special events.

​
How to Use

1

Install and import the necessary libraries (e.g., pandas). Make sure you have the date feature classes accessible in your Python environment.

2

Create an instance of the class (CountryHolidays or SpecialDates) with appropriate parameters (e.g., country codes or dictionaries of special dates).

3

Generate or retrieve your date range (e.g., using pd.date_range) covering the period you want to evaluate.

4

Call the class instance with your date range to get a DataFrame of date flags.

5

Integrate the resulting DataFrame into your larger dataset before fitting or predicting with TimeGPT.

​
CountryHolidays

Use CountryHolidays when you need holiday flags for multiple countries in your time series.

CountryHolidays(countries: List[str])

Given a list of countries, returns a DataFrame containing holiday flags for each of these countries.

country-holidays example
import pandas as pd
from your_module import CountryHolidays

# Example usage:
c_holidays = CountryHolidays(countries=['US', 'MX'])
periods = 365 * 5
dates = pd.date_range(end='2023-09-01', periods=periods)
holidays_df = c_holidays(dates)
holidays_df.head()

​
SpecialDates

Use SpecialDates for custom events or non-official holidays that matter to your specific domain.

SpecialDates(special_dates: Dict[str, List[str]])

Given a dictionary mapping special events to their dates, returns a DataFrame containing flags for these special dates.

special-dates example
import pandas as pd
from your_module import SpecialDates

# Example usage:
special_dates = SpecialDates(
    special_dates={
        'Important Dates': ['2021-02-26', '2020-02-26'],
        'Very Important Dates': ['2021-01-26', '2020-01-26', '2019-01-26']
    }
)

periods = 365 * 5
dates = pd.date_range(end='2023-09-01', periods=periods)
special_df = special_dates(dates)
special_df.head()

​
Notes on this Conversion

You can now use CountryHolidays and SpecialDates in your project to easily add date-based features, leveraging the power of holiday and event detection for forecasting or general time series analysis.