Calendar regressors for a marketing mix model: Fourier terms for a smooth
yearly cycle, and flags for the periods that contain a holiday. Both return
a data frame with one row per element of index, in the same order, ready
to cbind() to a model frame or to pass as controls to
tune_carryover().
Usage
fourier_terms(index, harmonics = 2, cycle = NULL, prefix = "season")
holiday_flags(
index,
holidays,
period = NULL,
align = c("start", "end"),
prefix = "holiday"
)Arguments
- index
The time of each row. For
fourier_terms(), aDatevector, or a numeric vector withcyclegiven. Forholiday_flags(), aDatevector. It need not be sorted and may repeat dates, as a panel does. A missing value gives a row ofNA.- harmonics
Number of sine and cosine pairs, a whole number of at least 1. Harmonic
krepeatsktimes per cycle, soktimes a year for aDateindex.- cycle
Length of one seasonal cycle in the units of a numeric
index, such as52for a week number or12for a month number. Required for a numericindex. ADateindex always uses the calendar year, socyclemust then be left out.- prefix
Start of every column name, a single string.
- holidays
The holiday dates: a
Datevector for a single flag, or a named list ofDatevectors for one flag per element. Dates may repeat and need not be sorted, but must not be missing.- period
Length of each row's period: a single positive number of days, or a
difftime.NULL(the default) takes the median step between consecutive distinct dates inindex, which is 7 for weekly data and 1 for daily data.- align
Where each date sits in its period:
"start"(the default) when dates mark the first day of the period, as week-commencing dates do, or"end"when they mark the last day, as week-ending dates do.
Value
A data frame with one row per element of index, in the same
order, and default row names.
fourier_terms() returns 2 * harmonics numeric columns, a sine and a
cosine for each harmonic in turn: <prefix>_sin1, <prefix>_cos1,
<prefix>_sin2, <prefix>_cos2 and so on.
holiday_flags() returns integer columns holding 1 for a period that
contains a holiday and 0 otherwise. A Date vector of holidays gives one
column named prefix; a named list gives one column per element, named
<prefix>_<element name>, in the order of the list.
Details
Fourier terms. For a Date, the time of year is t = (d - 1) / 365.25,
where d is the day of the year, 1 for 1 January. For a numeric index,
t = index / cycle. Harmonic k contributes sin(2 * pi * k * t) and
cos(2 * pi * k * t). Every year starts at t = 0, so a calendar date has
the same terms every year, except that from 29 February a leap year is one
day further along: its 31 December reaches t = 365 / 365.25. Each
harmonic adds two columns, and so two coefficients to the model; the first
few describe a smooth seasonal shape, and later ones sharper peaks.
Holiday flags. Each date in index marks one end of a period of
period days. With align = "start" the period runs from the date up to,
but not including, the date plus period; with align = "end" it runs
from the day after the date minus period up to and including the date. A
row is flagged when at least one holiday falls inside its period, so with
daily data a row is flagged on the holiday itself. A holiday that falls in
no row's period, such as one in a missing week, is not flagged anywhere.
Every period has the same length, which suits daily and weekly data.
When period is inferred and some dates are closer together than it, the
periods overlap, a holiday can be flagged in two rows, and a warning says
so. That happens with monthly data, whose months run from 28 to 31 days,
and with a panel whose series start their weeks on different days. Give
period for the panel, and flag monthly data by each holiday's month.
See also
tune_carryover() and tune_carryover_joint(), which take
control columns as controls; mm_weekly, whose seasonality and
holiday columns are simulated stand-ins for these controls.
Examples
data(mm_weekly)
north <- mm_weekly[mm_weekly$geo == "north", ]
# Two harmonics of the yearly cycle, from week-commencing dates
season <- fourier_terms(north$date, harmonics = 2)
head(round(season, 3))
#> season_sin1 season_cos1 season_sin2 season_cos2
#> 1 0.017 1.000 0.034 0.999
#> 2 0.137 0.991 0.272 0.962
#> 3 0.255 0.967 0.493 0.870
#> 4 0.369 0.929 0.687 0.727
#> 5 0.478 0.878 0.840 0.542
#> 6 0.580 0.814 0.945 0.326
# A numeric index needs the length of its cycle
head(round(fourier_terms(1:104, harmonics = 1, cycle = 52), 3))
#> season_sin1 season_cos1
#> 1 0.121 0.993
#> 2 0.239 0.971
#> 3 0.355 0.935
#> 4 0.465 0.885
#> 5 0.568 0.823
#> 6 0.663 0.749
# Flag the weeks that contain Christmas Day or Black Friday
holidays <- list(
christmas = as.Date(c("2023-12-25", "2024-12-25", "2025-12-25")),
black_friday = as.Date(c("2023-11-24", "2024-11-29", "2025-11-28"))
)
flags <- holiday_flags(north$date, holidays)
north$date[flags$holiday_christmas == 1]
#> [1] "2023-12-25" "2024-12-23" "2025-12-22"
# Week-ending dates flag the same weeks with align = "end"
week_ending <- north$date + 6
identical(holiday_flags(week_ending, holidays, align = "end"), flags)
#> [1] TRUE
# A table with one row per holiday becomes the list through split()
calendar <- data.frame(date = as.Date(c("2024-12-25", "2024-11-29")),
name = c("christmas", "black_friday"))
flags_2024 <- holiday_flags(north$date, split(calendar$date, calendar$name))
colSums(flags_2024)
#> holiday_black_friday holiday_christmas
#> 1 1
# Ready to bind to a model frame
model_data <- cbind(north[c("date", "revenue")], season, flags)
head(model_data)
#> date revenue season_sin1 season_cos1 season_sin2 season_cos2
#> 1 2023-01-02 27130 0.01720158 0.9998520 0.03439806 0.9994082
#> 2 2023-01-09 20433 0.13718540 0.9905454 0.27177674 0.9623603
#> 3 2023-01-16 20481 0.25518241 0.9668929 0.49346814 0.8697639
#> 4 2023-01-23 20565 0.36948368 0.9292372 0.68667598 0.7269636
#> 5 2023-01-30 17574 0.47843382 0.8781236 0.84024807 0.5422022
#> 6 2023-02-06 28722 0.58045493 0.8142924 0.94532005 0.3261442
#> holiday_christmas holiday_black_friday
#> 1 0 0
#> 2 0 0
#> 3 0 0
#> 4 0 0
#> 5 0 0
#> 6 0 0