date_features.mdx

---
title: "Date Features"
description: "Use holidays flags and special dates to improve your accuracy"
icon: "calendar"
---

<Info>
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.
</Info>

## Overview

<CardGroup>
  <Card title="CountryHolidays">

    Easily attach holiday flags for multiple countries based on a list of countries.
  </Card>
  <Card title="SpecialDates">

    Add flags for custom events or significant dates you define.
  </Card>
</CardGroup>

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.


<a
href="https://github.com/Nixtla/nixtla/blob/main/nixtla/date_features.py#LNone"
target="_blank" style={{ float: "right", fontSize: "smaller" }}>source</a>

#### CountryHolidays

> ``` text
>  CountryHolidays (countries:list[str])
> ```

*Given a list of countries, returns a dataframe with holidays for each
country.*

```python
import pandas as pd
```

|  | US_New Year's Day | US_Memorial Day | US_Independence Day | US_Labor Day | US_Veterans Day | US_Veterans Day (observed) | US_Thanksgiving | US_Christmas Day | US_Martin Luther King Jr. Day | US_Washington's Birthday | ... | US_Juneteenth National Independence Day (observed) | US_Christmas Day (observed) | MX_Año Nuevo | MX_Día de la Constitución | MX_Natalicio de Benito Juárez | MX_Día del Trabajo | MX_Día de la Independencia | MX_Día de la Revolución | MX_Transmisión del Poder Ejecutivo Federal | MX_Navidad |
|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
| 2018-09-03 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | ... | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 2018-09-04 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | ... | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 2018-09-05 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | ... | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 2018-09-06 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | ... | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 2018-09-07 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | ... | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |

```python
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()
```

------------------------------------------------------------------------

<a
href="https://github.com/Nixtla/nixtla/blob/main/nixtla/date_features.py#LNone"
target="_blank" style={{ float: "right", fontSize: "smaller" }}>source</a>

#### SpecialDates

> ``` text
>  SpecialDates (special_dates:dict[str,list[str]])
> ```

*Given a dictionary of categories and dates, returns a dataframe with
the special dates.*

```python
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)
holidays_df = special_dates(dates)
holidays_df.head()
```

|            | Important Dates | Very Important Dates |
|------------|-----------------|----------------------|
| 2018-09-03 | 0               | 0                    |
| 2018-09-04 | 0               | 0                    |
| 2018-09-05 | 0               | 0                    |
| 2018-09-06 | 0               | 0                    |
| 2018-09-07 | 0               | 0                    |