Seasonality and Holiday Effects
Given a Polars offset alias
functime.offsets.freq_to_sp to return a list of seasonal periods.
Method 1. Dummy Variables / Categorical
add_calendar_effects to generate datetime and calendar effects.
functime supports two strategies to model seasonality as discrete features: though a categorical column (useful for forecasters with native categorical features support e.g.
lightgbm) or multiple binary columns (i.e. one-hot encoding). Check out Chapter 7.4: Seasonal dummy variables for a quick primer.
If you choose the dummy variable strategy, beware of the "dummy variable trap" (i.e. remember to set
fit_intercept=False if you decide to include all dummy columns).
- minute: 1, 2, ..., 60 (in a day)
- hour: 1, 2, ..., 24 (in a day)
- day: 1, 2, ..., 31 (in a month)
- weekday: 1, 2, ..., 7 (in a week)
- week: 1, 2,..., 52 (in a year)
- quarter: 1, 2, ..., 4 (in a year)
- year: 1999, 2000, ..., 2023 (any year)
from functime.seasonality import add_calendar_effects # Returns X with one categorical column "month" with values 1,2,...,12 X_new = X.pipe(add_calendar_effects(["month"])).collect() # Returns X with one-hot encoded calendar effects # i.e. binary columns "month_1", "month_2", ..., "month_12" X_new = X.pipe(add_calendar_effects(["month"]), as_dummies=True).collect()
Method 2. Fourier Terms
Fourier terms are a common way to model multiple seasonal periods and complex seasonality (e.g. long seasonal periods 365.25 / 7 ≈ 52.179 for weekly time series). For every seasonal period
sp and Fourier term
k=1,..,K pair, there are 2 fourier terms
Fourier terms can be used to approximate a continuous periodic signal, which can then be used as exogenous regressors to model seasonality. Chapter 12.1: Complex Seasonality from Hyndman's textbook "Forecasting: Principles and Practice" contains a great practical introduction to this topic.
add_fourier_terms returns the original
X DataFrame along with the Fourier terms as additional columns.
For example, if
X_new would contain the columns
Modelling Holidays / Special Events
functime has a wrapper function around the
holidays Python package to generate categorical features for special events. Dates without a holiday are filled with nulls.
from functime.seasonality import add_holiday_effects # Returns X with two categorical columns "holiday__US" and "holiday__CA" north_america_holidays = add_holiday_effects(country_codes=["US", "CA"]) X_new = X.pipe(north_america_holidays).collect() # Returns X with one-hot encoded holidays (e.g. "holiday__US_christmas) north_america_holidays = add_holiday_effects(country_codes=["US", "CA"], as_dummies=True) X_new = X.pipe(north_america_holidays).collect()