Sam Austinon November 2, 202614 min read

Holiday and Event Features for Forecasting: How to Add Them in Python

Holiday and Event Features for Forecasting: How to Add Them in Python
Contents

Figure 1: Holiday and Event Features for Forecasting: How to Add Them in Python — a weekly rhythm and a trend will not explain a crater that only appears on the fourth Thursday of November

Your demand curve has a weekly rhythm, a trend and a mysterious crater every fourth Thursday of November. A model that only knows the weekday cannot explain the crater. Holiday features can, and they take about ten lines to add.

I tested the options on a synthetic series, so I can show you which ones earn their keep. One result surprised me, and I will flag it when we get there.

Why a Plain Date Column Is Not Enough

Holidays break the usual calendar features in three ways.

  1. They move. Thanksgiving is the fourth Thursday of November, so day-of-year cannot find it.
  2. They shift when they land on a weekend. The pandas federal calendar returned July 3 as the observed date in 2020 and 2026, because July 4 falls on a Saturday in both years.
  3. Their effect spills over. The day before and the day after often behave differently from ordinary days.

Step 1: Get the Dates From a Calendar, Not From Memory

Pandas ships a US federal calendar [1]:

from pandas.tseries.holiday import USFederalHolidayCalendar

cal = USFederalHolidayCalendar()
dates = cal.holidays("2016-01-01", "2030-12-31", return_name=True)

Two things I verified.

It covers future dates. The calendar returned 11 holidays for 2030. That matters, because holiday features must be known at forecast time, unlike your target.

Rules change over time. It returned no Juneteenth for 2019 and one for 2022. If your history predates a holiday's rule, old years simply will not have it.

For other countries, the usual route is the holidays package. Its README describes holidays.country_holidays("US") as returning a dict-like object, supports subdivisions through subdiv, and says it covers 250 country codes [5]. I could not install it in my environment, so I never ran it. Everything below uses the pandas calendar.

Step 2: Add Your Own Events

Holidays that are not official still matter. Black Friday is not a federal holiday, but you can define it as a rule in pandas [2]:

from dateutil.relativedelta import TH
from pandas.tseries.holiday import AbstractHolidayCalendar, Holiday, USFederalHolidayCalendar
from pandas.tseries.offsets import DateOffset

BF = Holiday("Black Friday", month=11, day=1,
             offset=[DateOffset(weekday=TH(4)), DateOffset(days=1)])

class MyCal(AbstractHolidayCalendar):
    rules = USFederalHolidayCalendar.rules + [BF]

My check: for 2023 it returned November 24, the day after Thanksgiving on November 23. Promotions, product launches and sports finals work the same way, as long as you know their dates ahead of time.

Step 3: Turn Dates Into Features

I built a synthetic daily demand series of 3,288 rows, covering 2016 to 2024. By construction, demand moves differently on each holiday, rises the day before, dips the day after, and spikes on Black Friday. Then I compared feature sets with a gradient-boosting model, min_samples_leaf=2, and five forward folds.

I report two numbers: MAE on all days, and MAE on the 290 rows within one day of a holiday or event, where holiday features should matter.

Feature set All days Near holidays
Weekday + trend only 16.47 34.34
+ flag from nominal dates 14.20 29.43
+ flag from calendar (observed dates) 12.66 29.05
+ days to next / since previous 11.28 23.70
+ holiday name as integer codes 10.42 20.62
+ holiday name as one-hot columns 9.53 19.06
+ holiday name as pandas categorical 11.15 21.84

Reading the table:

  • A holiday flag helps a lot. Near-holiday error fell from 34.34 to 29.05.
  • Observed dates beat nominal dates, but only slightly. 13 of the 103 holiday instances in my window were observed on a different day than their nominal date, so the gap is small by construction.
  • Distance features were the biggest single jump. Days to the next holiday and days since the last one cut near-holiday error from 29.05 to 23.70. They let the model learn "the day before" and "the day after" without writing a rule for each.
  • Names helped. One-hot columns took near-holiday error to 19.06, because the model could finally tell Christmas from Memorial Day.

Compute the distance features from the calendar, clip them (I used 0 to 7 days) and keep them numeric. They use only dates, so they are safe to build for future rows.

The Surprise: Native Categorical Helped, but Less

Look at the last row. Passing the holiday name as a pandas categorical column, which scikit-learn's histogram gradient boosting treats as categorical by default ("from_dtype"), scored 21.84 near holidays [3] [4]. One-hot columns, built from the same names, scored 19.06.

So the native route worked, just not as well as the encoded one. It is not a null result in my run: it clearly beat leaving the name out at 23.70.

I cannot fully explain the gap. One plausible reason is that with one to seven occurrences of a given holiday in a training fold, the categorical splitter has very little to work with, while one-hot at least lets the tree isolate a single day's flag. Do not read this as "native categorical never works" or "native categorical always wins." Do read it as a reason to compare an encoded version against the native one on your own data rather than trusting either.

Rare Events and min_samples_leaf

Black Friday appeared between one and seven times in each training fold. By default, HistGradientBoostingRegressor requires 20 samples per leaf. That is more than an event with a handful of occurrences can ever supply.

I ran the same comparison at the default and at 2:

Setting All days Near holidays
Distance, min_samples_leaf=20 9.37 26.90
+ names as codes, min_samples_leaf=20 9.40 24.44
Distance, min_samples_leaf=2 11.28 23.70
+ names as codes, min_samples_leaf=2 10.42 20.62

Names helped at both settings, and helped more with the smaller leaf. I could not reproduce a sharp cutoff where they stop working entirely.

The trade-off is real, though: the smaller leaf improved near-holiday error and made the all-days error worse, 9.37 to 11.28, because tiny leaves fit noise everywhere else. If your events are rare, lower the setting, then check the overall error as well as the holiday error.

A Checklist for Holiday Features

  1. Use a calendar library, not hand-typed dates, and confirm it covers your forecast horizon.
  2. Use observed dates when weekends shift holidays, if your business follows them.
  3. Add custom events as rules or a dataframe, only if you will know their dates in advance.
  4. Add distance features (to next, since previous), clipped.
  5. Add the holiday name as codes or one-hot columns, and test the native categorical route separately.
  6. Check rare events against min_samples_leaf and your training counts.
  7. Never use a feature you will not know at forecast time.

Common Pitfalls

  1. Hardcoding month and day for a floating holiday. Thanksgiving has no fixed date, so month == 11 & day == 27 is wrong most years.
  2. Forgetting that the observed date is the one your business reacts to. July 3 in 2020 is the day to flag, not July 4.
  3. Adding a promotion flag you only learn about afterwards. That is leakage, and it flatters the model.
  4. Building holiday features only up to today. Your forecast rows need them too, or the model sees a gap at the horizon.
  5. Trusting the native categorical route without a comparison. It helped here, but less than one-hot.
  6. Judging the leaf setting on holiday error alone. Lowering it helped near holidays and hurt everywhere else.

Best Book to Read

CoverBookDescriptionGet it
Cover of “Time Series Forecasting in Python” Time Series Forecasting in Pythonby Marco Peixeiro works through the calendar, event and seasonality features used here with runnable Python, and keeps the evaluation honest by scoring on held-out future windows rather than a shuffled split. View on Amazon

As an Amazon Associate I earn from qualifying purchases. Links on this page are affiliate links, and I may earn a commission at no extra cost to you.

Wrapping Up

Holiday features paid off in my test: error near holidays fell from 34.34 to about 19.06 once the flag, the distance features and the names were in. The distance features are the best value for the effort, since they capture the shoulders around each event, and the holiday name is what lets the model tell one event from another.

Take one series you forecast, add the calendar flag and the two distance columns, and rerun your forward validation. If error near holidays drops sharply, you know where your next improvement is hiding.

Frequently Asked Questions

How do I add US holidays to a pandas dataframe?

Use USFederalHolidayCalendar from pandas.tseries.holiday. Call holidays(start, end, return_name=True) to get a DatetimeIndex of observed dates with their names, then flag rows where the date is in that index. It needs no extra package and it returns dates, not just names.

Does the pandas holiday calendar cover future years?

Yes. It computes rules rather than looking up a table, so it returned 11 holidays for 2030 in my run. That matters because holiday features must be known at forecast time. The rules themselves can change: the calendar returned no Juneteenth for 2019 and one for 2022.

How do I add Black Friday or another custom event to pandas?

Define a Holiday rule with a month, a day and an offset. Black Friday is November 1 plus the fourth Thursday plus one day, which returned November 24 in 2023. Add the rule to a custom calendar that extends USFederalHolidayCalendar, then call holidays on it as usual.

Why do holiday features not improve my model?

Three common reasons. The effect may sit on the observed date while your flag sits on the nominal one, so shifted holidays are missed. The model may have too few examples of each event to learn a separate effect. And a holiday flag alone cannot express the days around the event, which is why distance features helped most in my test.

Should I pass the holiday name as a pandas categorical?

Compare it against one-hot before you commit. In my run the categorical version improved near-holiday error from 23.70 to 21.84 MAE, while one-hot reached 19.06, so it helped but lost to the encoded version. With one to seven occurrences of an event per training fold, there is very little for a categorical split to learn from.

Sources

What are You Looking For?

esc