Calendars, holidays and events
- Lesson 6
- 30 min
- Module 2: Read a time series
Where we are
We have measured how a series remembers its past. Some days, the past is not the best guide: Easter moves, a promotion doubles sales, and a price rise changes the level. In this lesson, we put these events in a calendar and ask what a model can know when it forecasts.
Lesson 6 of 27 · Forecasting and Time Series: Predict What Comes NextCalendars, holidays and events
1. Forecasts serve decisions
2. Read a time series
3. Baselines and honest testing
4. Statistical forecasters
5. Machine learning forecasters
6. Hard series and many series
7. Uncertainty and the decision
8. Run a forecast in production
What you will be able to do
Find the events that move demand on a known date: Easter, Black Friday, promotions and price changes. Then give them to a forecast as known future inputs. A forecast that only copies the past puts these events on the wrong days.
NotebookDo this lesson in a notebook
The notebook has every code cell, task and check of this lesson. It finds Easter in the calendar, measures the Easter, Black Friday and promotion effects, and checks which files reach into the future. Its setup cells install pandas and statsforecast and download the practice data, so it needs no local setup. About 30 minutes.
Colab and Kaggle open your own copy. They need a free Google or Kaggle account. Stuck? See the solution notebook.
Before you startWhat to know and to have ready
What you need to know
- The yearly season and the remainder, from Trend, season and noise. Black Friday ended up in the remainder there.
- Lags and the weekly season in the ACF, from Yesterday predicts today.
- The Larkfield files
calendar.csv,promotions.csvandprice_changes.csv, from Meet the Larkfield data.
What you need on your computer
Nothing for the notebook route: it runs in Colab or Kaggle. For a local route, save the notebook in the folder larkfield that you made in Meet the Larkfield data, and choose the kernel .venv. The notebook reuses the data in larkfield-forecasting.
Tested with Python 3.12 and pandas 2.3.3 on macOS. Windows and Colab were not tested.
A bakery’s diary
Section titled “A bakery’s diary”A baker plans next week’s bread. She looks at last week’s sales, because yesterday predicts today. But she also opens her diary. Next Saturday, the town has a market, and she sells twice as much on market days. On Thursday, she has a half-price offer on rolls. In two weeks, the price of flour goes up, so her bread will cost more.
Last week’s sales cannot know any of this. The diary can. And the diary is not a guess: the market, the offer and the new price are planned. She knows them on the day she plans.
But the diary does not know the weather, or how many customers will come. She must still forecast those.
The problem: the past puts events on the wrong days
Section titled “The problem: the past puts events on the wrong days”The last lesson showed that a forecast can copy the same weekday from the past. Over a year, a natural choice is “the same day 52 weeks before”. That is 364 days, so a Saturday copies a Saturday.
Now look at Easter. Garden products sell more on the Easter weekend. Here are Larkfield’s sales of two garden categories, plants and seeds and garden tools, around Easter 2025:
Text description of the chart
Daily sales of the two garden categories from 4 April to 4 May 2025. On the other days, sales are between 464 and 717 units, with higher Saturdays. On the four Easter days, sales are 775 (Good Friday), 974 (Saturday), 930 (Sunday) and 709 (Monday). The same weekdays one week before had 514, 578, 582 and 476, and one week after 532, 692, 569 and 543.
The Easter weekend of 2025 is high on all four days. Now the problem. In 2026, Easter is on 5 April, two weeks earlier. What does “the same day 52 weeks before” copy?
| Day in 2026 | Holiday in 2026 | Copies the day | Holiday on the copied day |
|---|---|---|---|
| Fri 3 April | Good Friday | Fri 4 April 2025 | none |
| Sat 4 April | none (inside the Easter weekend) | Sat 5 April 2025 | none |
| Sun 5 April | Easter Sunday | Sun 6 April 2025 | none |
| Mon 6 April | Easter Monday | Mon 7 April 2025 | none |
| Fri 17 April | none | Fri 18 April 2025 | Good Friday |
| Mon 20 April | none | Mon 21 April 2025 | Easter Monday |
The copy fails twice. On Easter 2026, it copies ordinary days, so it forecasts too little. Two weeks later, it copies Easter 2025 into ordinary days, so it forecasts too much. Kenji would run short of garden goods at Easter and have extra stock two weeks later.
The yearly season of Trend, season and noise has the same problem. It learns one value per date, so it spreads Black Friday over two dates, and it would spread Easter too.
The idea: events from the calendar
Section titled “The idea: events from the calendar”So we do what the baker does. We keep a calendar of events and give it to the forecast as extra columns.
An event is a day, or a few days, when demand changes for a known reason. There are three kinds at Larkfield:
- Holidays. Some are on a fixed date: Christmas is always on 25 December. Some move: Easter follows the moon, and Black Friday is the Friday after the fourth Thursday of November.
- Promotions. Larkfield plans a promotion week for a product, with a discount. During the week, the product sells more.
- Price changes. A permanent price change moves the level of a product for good, from its first day.
All three are known in advance. A forecast may use a known value for a future day, because Kenji really has it on the day he forecasts. Such an input is called a known future input (some libraries say “future exogenous variable”: “exogenous” means “from outside the series”).
A tiny example: one event column
Section titled “A tiny example: one event column”Take four days: the Thursday before Good Friday, and three Easter days. The column easter is 1 from Good Friday to Easter Monday, and 0 on other days. We build it from calendar.csv: its Good Friday, its Easter Monday and the days between them. A model learns how much an Easter day adds. Here, the “model” is one number: Easter days sell about 1.5 times the normal level.
| Day | Normal level | easter |
Forecast |
|---|---|---|---|
| Thu 17 April 2025 | 600 | 0 | 600 |
| Fri 18 April 2025 | 600 | 1 | 600 × 1.5 = 900 |
| Sat 19 April 2025 | 600 | 1 | 900 |
| Sun 20 April 2025 | 600 | 1 | 900 |
The normal level of 600 is a round number for this example. The column moves with Easter. In 2026, it is 1 on 3 to 6 April, so the forecast puts the jump on the right days. The column comes straight from calendar.csv.
Larkfield’s events, measured
Section titled “Larkfield’s events, measured”Easter
Section titled “Easter”How large is the Easter effect? The notebook compares the four Easter days of 2025 with the same weekdays one week before and one week after:
week before Easter week afterFriday 514 775 532Saturday 578 974 692Sunday 582 930 569Monday 476 709 543Easter effect: x 1.51The four Easter days sold 3,388 units. The same days one week before and after sold 2,150 and 2,336, a mean of 2,243. So Easter multiplies garden sales by about 1.51. Larkfield’s calendar has Easter Sunday on 20 April 2025 and on 5 April 2026. The first day of the data, Monday 1 April 2024, is Easter Monday of 2024.
Black Friday
Section titled “Black Friday”- Black Friday
- The same weekday one week before
Text description of the chart
Four columns. Black Friday 2024 (29 November) had 1,059 orders; the Friday one week before had 439. Black Friday 2025 (28 November) had 1,224 orders; the Friday one week before had 605.
Black Friday 2024 had 2.4 times the orders of the Friday before, and Black Friday 2025 had 2.0 times. Its date moves, from 29 November to 28 November, so a column black_friday from the calendar puts it on the right day. The days around it also change: the Monday after, Cyber Monday, is high too, with 1,012 orders in 2024 and 1,136 in 2025.
Promotions
Section titled “Promotions”promotions.csv lists each planned promotion week: the product, the first and last day, and the discount. It has 410 promotions. 63 of them start in the 13 weeks after the history: the shop has already planned them. In demand.csv.gz, the column on_promotion is 1 on a promotion day.
Here is P141, a duvet, with a 25% promotion from 8 to 14 September 2025, a situation we planted:
- P141 units sold per day
- Promotion days (25% off)
Text description of the chart
Daily sales of product P141 from 18 August to 28 September 2025. Outside the promotion, most days have 7 to 19 units. On the seven promotion days, 8 to 14 September, sales are 39, 26, 31, 14, 29, 18 and 26. The promotion week sold 183 units in total; the week before sold 80. After the promotion, sales go back to their normal level, with a few low days.
On promotion days, P141 sold 2.09 times its normal daily level. Over all 135 products that had a promotion, the median uplift is 1.87: a typical promotion almost doubles sales. In the notebook’s Your turn, you compute this median yourself.
A forecast that does not know the promotion plan is too low in every promotion week. If it learns from a promotion as if it were normal demand, it is also too high in the weeks after it.
Price changes
Section titled “Price changes”price_changes.csv has three permanent price changes, each announced in advance. The garden hose P077 went from 24.99 to 31.99 on 2 June 2025, after a supplier price rise. P112 got a new price with a new model in January 2025, and P160 got a price cut in October 2025 to clear its stock. A price rise lowers the level of a product for good. Breaks and changes handles a level that moves.
What a forecast can know on the day it is made
Section titled “What a forecast can know on the day it is made”Every input of a forecast must pass one test: would Kenji have this value on the day he forecasts? For each input, imagine the forecast day and look forward. It is the cut-off of Frame the forecast: the last day of data, a Sunday for Kenji’s Monday order.
Text description of the diagram
On the left, the past: sales and stock-outs, orders and tickets, the weather so far and the promotions that ran. All of it is known. It leads to the cut-off, a Sunday: the data runs up to Sunday, and Kenji orders on Monday. From there, two arrows go to the next 14 days. A solid arrow, “may use”, leads to the known future inputs: the calendar (Easter, Black Friday, Christmas), the planned promotions and the announced price changes. A dashed arrow, “must forecast first”, leads to what is not known: the sales and stock-outs, the orders and tickets, and the weather.
The Larkfield files follow this rule. In the notebook’s section 5:
sales (demand.csv.gz) last date 2026-03-29weather.csv last date 2026-03-29calendar.csv last date 2026-06-28promotions.csv last date 2026-06-28promotions that start after the history: 63The sales and the weather end on the last day of the history. The calendar and the promotion plan run 13 weeks further, because the shop knows them in advance.
When to add events, and what they cost
Section titled “When to add events, and what they cost”Add an event column when three things are true. The event moves demand. It comes back, every year or with every promotion. And its date is known before the forecast. Easter, Black Friday, Christmas, promotions and price changes pass all three tests.
Do not add a column for a one-time event that will not come back. And do not add a column whose future value you do not know.
Events cost something too:
- Few examples. Two years hold two Black Fridays and two Easters (plus the Easter Monday on the first day). An effect learned from two examples is rough. Say so when you use it.
- A plan can change. A promotion can be cancelled or moved. The forecast is only as good as the plan it reads. Mei must keep
promotions.csvup to date. - Not every method takes them. The naive methods of Module 3 cannot use event columns. Statistical and machine learning methods in Modules 4 and 5 can.
Common mistake
An input from the future
Symptom: Tomás builds a parasol forecast with the temperature of each day as an input. Parasols sell on hot days, and in his backtest the forecast is very good. Then Kenji tries to run it on Sunday 29 March 2026, for the next two weeks. The table of inputs has no temperature for the days ahead:
weather = pd.read_csv("data/weather.csv", parse_dates=["date"])print(weather["date"].max())2026-03-29 00:00:00The model cannot run, or it runs with empty values and gives nonsense.
Cause: the temperature of a future day is not known on the forecast day. In the backtest, Tomás used the real temperature of the days he forecast, values that nobody has in advance. The test was too good, because it used information from the future. This is leakage: an input that would not exist at the moment of the prediction. The machine learning course explains it in Train, validation and test sets.
Fix: for each input, ask “would Kenji have this value on the forecast day?”. Use the calendar, the promotion plan and the announced prices freely. For the weather, use a weather forecast made on the forecast day, in the backtest too, or leave the weather out. The same holds for on_promotion in demand.csv.gz: it exists only for past days, so take future promotions from promotions.csv.
Consequence in forecasting: leakage makes a forecast look better in testing than it can ever be in use. The team picks the leaky model, and it fails on its first real week, often just when it matters, such as a heat wave.
Guided practice: find the events in the notebook
Section titled “Guided practice: find the events in the notebook”- Open the notebook from the box Do this lesson in a notebook at the top of this page.
- Run the setup cells and the helper cell. The data cell ends with
Ready: 403758 rows of daily sales. - In section 1, predict whether the copied days are holidays. Then run the cell. You see an empty holiday column for 4 to 7 April 2025.
- In section 2, run the Easter cell. You see
Easter effect: x 1.51. - In section 3, run the Black Friday cell. You see
1059and439for 2024, and1224and605for 2025. - In section 4, predict P141’s uplift. Then run the cell. You see
week before: 80 | promotion week: 183andP141 uplift: x 2.09. - In section 5, run the cell. You see that the weather ends on
2026-03-29and the promotions on2026-06-28.
Your turn: the uplift of every product
Section titled “Your turn: the uplift of every product”Change one thing: from one product to all of them. Compute P141’s uplift for every product that had a promotion: the mean daily sales on promotion days divided by the mean on other days. Use the table daily from section 4. Before you run it, predict: will the median be higher or lower than P141’s 2.09? Put the median, rounded to 2 decimals, in median_uplift.
Show the answer
on = daily[daily["promo"] == 1].groupby("product_id")["sales"].mean()off = daily[daily["promo"] == 0].groupby("product_id")["sales"].mean()uplift = (on / off).dropna()median_uplift = round(float(uplift.median()), 2)print(len(uplift), "products, median uplift", median_uplift)135 products, median uplift 1.87The median is lower than P141’s: P141 is a strong case, planted to show the effect. But 1.87 is still close to double. The other 65 products had no promotion in the history, so dropna() removes them: a product with no promotion days has no uplift to measure.
Knowledge check
Section titled “Knowledge check”Check your understanding
Kenji forecasts garden sales for April 2026 with 'the same day 52 weeks before'. Explain what goes wrong around Easter, with the dates.
Show the answer
Easter 2025 was on 20 April and Easter 2026 is on 5 April. For the Easter days of 2026, 3 to 6 April, the copy takes 4 to 7 April 2025. Those were ordinary days, so the forecast is too low by about a third: Easter days sold about 1.51 times the normal level. For 17 to 20 April 2026, ordinary days, it copies Easter 2025, so the forecast is too high. The fix is an Easter column from the calendar, which moves with the date.
Does your answer have the main points of ours?
Sign in and enroll in the course to save your answers. Every check counts toward the certificate.
Check your understanding
For each input, say if a 14-day forecast made on a Sunday may use its value for the days ahead: (a) the calendar's holidays, (b) the planned promotions, (c) the temperature, (d) the stock-out flag, (e) an announced price change.
Show the answer
(a) Yes: holidays are known years ahead. (b) Yes: the promotions are planned, and promotions.csv runs to the end of June 2026. (c) No: the temperature of a future day is not known. Use a weather forecast made on the forecast day, or leave it out. (d) No: a stock-out is only known when it happens. (e) Yes: it is announced in advance. The test is always the same: would Kenji have the value on the forecast day?
Does your answer have the main points of ours?
Sign in and enroll in the course to save your answers. Every check counts toward the certificate.
Check your understanding
P141 sold 183 units in its promotion week and 80 in the week before. A forecast learns from these weeks as if they were normal demand. Predict what it does in the next normal week, and say what to do instead.
Show the answer
It takes the promotion week as a sign that P141’s normal level went up, so it forecasts too much for the next normal weeks. Kenji orders stock that does not sell. Instead, give the forecast the promotion as an input: a column that is 1 on promotion days, from promotions.csv. Then the model learns the uplift (about ×2 for P141, ×1.87 for the median product) apart from the normal level. It applies the uplift only in planned promotion weeks.
Does your answer have the main points of ours?
Sign in and enroll in the course to save your answers. Every check counts toward the certificate.
Recap
- An event changes demand on a known date: a holiday, a promotion, a price change. Some holidays move: Easter was on 20 April 2025 and is on 5 April 2026.
- “The same day 52 weeks before” puts a moving event on the wrong days. A season of fixed length does the same.
- Larkfield’s events, measured: Easter multiplies garden sales by 1.51. Black Friday doubles the orders or more (1,059 against 439, 1,224 against 605). A typical promotion multiplies sales by 1.87.
- Events are known future inputs when the shop knows them on the forecast day: the calendar, the promotion plan and announced prices. Sales, stock-outs and the weather of future days are not known.
- An input with a value from the future is leakage: the backtest looks good, and the forecast fails in use.
You can now give a forecast the events that it can know. The data still has holes: a missing day, and a stock-out that looks like no demand. Next, you clean them without hiding real demand.