Skip to content
Français

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.

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 notebookColab · Kaggle · GitHub

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 readyAbout 30 minutes

What you need to know

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 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:

Garden sales jump on the four Easter days, Good Friday 18 April to Easter Monday 21 April 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.

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:

  1. 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.
  2. Promotions. Larkfield plans a promotion week for a product, with a discount. During the week, the product sells more.
  3. 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”).

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.

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 after
Friday 514 775 532
Saturday 578 974 692
Sunday 582 930 569
Monday 476 709 543
Easter effect: x 1.51

The 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
  • The same weekday one week before
Black Friday more than doubles Larkfield's daily orders: 1,059 against 439 in 2024, and 1,224 against 605 in 2025.
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.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)
P141's sales jump in its promotion week: 183 units, against 80 in the week before.
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.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.

Four boxes. The past, all known: sales and stock-outs, orders and tickets, weather so far, promotions that ran. An arrow leads to the cut-off: Sunday, with the data up to Sunday; Kenji orders on Monday. From the forecast day, a solid arrow labelled may use leads to: the next 14 days, known: the calendar with Easter, Black Friday and Christmas, planned promotions, announced price changes. A dashed arrow labelled must forecast first leads to: the next 14 days, not known: sales and stock-outs, orders and tickets, the weather.
On the forecast day, the whole past is known. Of the days ahead, only the planned events are known. Everything else must be forecast.
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-29
weather.csv last date 2026-03-29
calendar.csv last date 2026-06-28
promotions.csv last date 2026-06-28
promotions that start after the history: 63

The 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.

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.csv up 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:00

The 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”
  1. Open the notebook from the box Do this lesson in a notebook at the top of this page.
  2. Run the setup cells and the helper cell. The data cell ends with Ready: 403758 rows of daily sales.
  3. 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.
  4. In section 2, run the Easter cell. You see Easter effect: x 1.51.
  5. In section 3, run the Black Friday cell. You see 1059 and 439 for 2024, and 1224 and 605 for 2025.
  6. In section 4, predict P141’s uplift. Then run the cell. You see week before: 80 | promotion week: 183 and P141 uplift: x 2.09.
  7. In section 5, run the cell. You see that the weather ends on 2026-03-29 and the promotions on 2026-06-28.

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.87

The 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.

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.

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?

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.

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.

Next: Clean without hiding demand