Meet the Larkfield data
- Lesson 3
- 35 min
- Module 1: Forecasts serve decisions
Where we are
We have two forecast frames on paper, one for stock and one for staff. We have not opened the data yet. In this lesson, we run the setup notebook, read Larkfield's orders, product demand and tickets, and meet the backtest table that every module of this course fills.
Lesson 3 of 27 · Forecasting and Time Series: Predict What Comes NextMeet the Larkfield data
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
Open Larkfield’s data and check that your setup works, before you build any forecast. You read every table, look at one product and find what is missing. Then you run the first row of the table that every module of this course fills.
NotebookDo this lesson in a notebook
The notebook has every code cell, task and check of this lesson. Its setup cells install pandas, statsforecast and matplotlib, download the Larkfield data (about 2 MB) and the course’s helper backtest.py, and check them. It needs no local setup, no account for the data and no key. It runs in about 10 seconds after the setup. About 35 minutes with the reading.
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
- Kenji’s and Grace’s forecast frames: demand, not sales; one product in one region per day; 14 days ahead; every Monday. From Frame the forecast.
- How to run a cell in a notebook and read a pandas table, from Machine Learning: From Problem to Reliable Model.
What you need on your computer
-
Colab or Kaggle (the easy route): a free Google or Kaggle account and a browser. Use the buttons in the box above.
-
Your own computer (optional): Python 3.12 and VS Code with its Python and Jupyter extensions. Make a folder and an environment for the course. On macOS or Linux:
Terminal window mkdir larkfield && cd larkfieldpython3.12 -m venv .venvsource .venv/bin/activatepython -m pip install ipykernelOn Windows, in PowerShell:
Terminal window mkdir larkfield; cd larkfieldpy -3.12 -m venv .venv.venv\Scripts\Activate.ps1python -m pip install ipykernelDownload the notebook with View on GitHub in the box above, and save it in the folder. Then open it in VS Code. Choose the kernel
.venv(top right). The notebook’s first cell installs the other packages into this environment.
Tested on macOS with Python 3.12.13, pandas 2.3.3 and statsforecast 2.1.1, in Jupyter. The Windows commands were not tested, and Colab and Kaggle were not tested.
The first morning in a new job
Section titled “The first morning in a new job”Think of your first morning as a new manager of a shop. You will plan next week’s orders. You do not start with a plan. You first open the cupboards and the books: what is on the shelves, what was sold, which pages are missing. Ten minutes of looking can save you from a plan built on a wrong page.
Forecasting is the same. Tomás built his forecast before he looked, and he trained it on empty-shelf days without knowing it. In this lesson, you look first. You also run one simple forecast through the course’s test, to check that everything works on your computer.
Open the notebook
Section titled “Open the notebook”The notebook makes a folder larkfield-forecasting next to itself and works inside it. The data goes into a folder data in it. Open it from the box Do this lesson in a notebook at the top of this page, then run the three setup cells in order:
-
Install the packages. It prints
pandas 2.3.3andstatsforecast 2.1.1. -
Get the practice data. It downloads the data, checks each file’s checksum (a fingerprint that changes if one byte of a file changes), and prints:
Ready: 403758 rows of daily sales (200 products, 3 regions), from 2024-04-01 to 2026-03-29. -
Load the helpers. It prints nothing.
If you see the Ready line, your setup works. If a cell shows an error, its last line says what to do. The notebook explains the two common errors: Could not download and wrong checksum.
The ten tables
Section titled “The ten tables”Larkfield’s data has ten tables. Before you read them in code, look at how they connect.
Text description of the diagram
The diagram has seven boxes. On the left, three boxes lead into the demand table. The first is products, with 200 products in 10 categories. The second is calendar, promotions and price_changes: the shop plans them in advance, and they run to 28 June 2026. The third is weather, with a dashed arrow, because it is known only for the history. The demand table has one row for each product, region and day. It has the price, a promotion flag, the units sold and the stock_out flag. An arrow leads from demand to orders: one row per sales channel and day, with about 1.65 units in each order. Another arrow leads to the two ticket tables, daily and hourly, because tickets follow the orders of the three days before. A last, dashed arrow labelled “Grace plans” leads to roster_hourly, the agents scheduled in each hour.
Every table has a date or an hour in each row. That makes each of them a set of time series. A time series is a list of values in time order, one value for each period: each day, or each hour. Here are the first seven days of Larkfield’s orders, with the three channels (web, app and phone) added up:
| Day | Mon 1 Apr 2024 | Tue 2 | Wed 3 | Thu 4 | Fri 5 | Sat 6 | Sun 7 |
|---|---|---|---|---|---|---|---|
| Orders | 550 | 536 | 536 | 515 | 562 | 566 | 621 |
The order of the values matters. If you shuffle these seven numbers, you lose the information that Sunday follows Saturday. The machine learning course could shuffle its rows. A forecast cannot, and the rest of this course depends on that.
The cell of section 1 reads all ten tables and prints their size and columns. Before you run it, predict: which table has the most rows, the daily sales of each product in each region, or the hourly tickets?
names = ["demand.csv.gz", "orders.csv", "tickets_daily.csv", "tickets_hourly.csv.gz", "roster_hourly.csv", "weather.csv", "calendar.csv", "products.csv", "promotions.csv", "price_changes.csv"]tables = {name: pd.read_csv(f"data/{name}") for name in names}for name, t in tables.items(): print(f"{name:22} {len(t):7} rows {list(t.columns)}")The output:
demand.csv.gz 403758 rows ['date', 'region', 'product_id', 'price', 'on_promotion', 'sales', 'stock_out']orders.csv 2181 rows ['date', 'channel', 'orders']tickets_daily.csv 2184 rows ['date', 'channel', 'tickets']tickets_hourly.csv.gz 52416 rows ['timestamp', 'channel', 'tickets']roster_hourly.csv 17472 rows ['timestamp', 'agents_scheduled']weather.csv 2184 rows ['date', 'region', 'temp_c']calendar.csv 819 rows ['date', 'weekday', 'holiday', 'is_holiday']products.csv 200 rows ['product_id', 'name', 'category', 'base_price', 'launch_date']promotions.csv 410 rows ['promotion_id', 'product_id', 'start', 'end', 'discount']price_changes.csv 3 rows ['product_id', 'date', 'new_price', 'reason']The demand table is the largest by far: 403,758 rows, one for each product, region and day. Its name follows the frame, but read its columns: it holds the units sold, and a stock_out flag. The real demand is not in it.
The history runs from Monday 1 April 2024 to Sunday 29 March 2026: 104 weeks. The calendar, the promotions and the price changes run 13 weeks further, to 28 June 2026, because a shop plans them in advance. A forecast may use them. The sales of those 13 weeks are the hidden future. We keep them back to score your forecasts at the end of the course, as reality would.
One product: the parasol
Section titled “One product: the parasol”The cell of section 2 adds up the parasol’s three regions for each day and draws two years. It marks the promotion days and the days when a region had no stock:
demand = pd.read_csv("data/demand.csv.gz", parse_dates=["date"])parasol = demand[demand["product_id"] == "P025"].groupby("date").agg( sales=("sales", "sum"), promotion=("on_promotion", "max"), stock_out=("stock_out", "max"))print(len(parasol), "days,", int(parasol["sales"].sum()), "parasols sold,", int(parasol["promotion"].sum()), "promotion days,", int(parasol["stock_out"].sum()), "days with a stock-out")The output:
727 days, 4201 parasols sold, 14 promotion days, 9 days with a stock-outThe notebook draws every day. The chart below adds the days up into weeks, so that you can read it on a phone.
Text description of the chart
The chart shows 104 weeks, from April 2024 to March 2026. The parasol sells from April to September and hardly at all in winter, when a week has between 1 and 13 sales. In the summer of 2024, the weekly sales stay above 100 from late June to early August. Their top is 159, in the first week of July. The highest week of the two years is a promotion week in September 2024, with 178 parasols. The summer of 2025 is lower: after a good May, most weeks stay under 70. One jump stands out: the heat-wave week of 30 June 2025, with 147 parasols, and the week after it, with 155.
727 days, and not 728: one day is missing. Section 4 finds it.
Sales are not demand, in the data
Section titled “Sales are not demand, in the data”In section 2, the notebook asks you to count the stock-out days of product P002, the black folding chair, in the north. Write p002_north_out, then run the check cell:
rows = demand[(demand["product_id"] == "P002") & (demand["region"] == "north")]p002_north_out = int(rows["stock_out"].sum())print(p002_north_out)9Check passed: p002_north_out is 9.These are nine days in a row, from 12 to 20 May 2025, with zero sales. It is the stock-out from the failure case of Frame the forecast. The data shows it only through the flag. Module 2 decides what to do with such days.
The backtest table
Section titled “The backtest table”Think of two weather apps on your phone. Which one should you trust? Every evening for a month, you write down what each app says for tomorrow. Every next evening, you write down the real weather. At the end of the month, you compare. Two rules make this fair. Each app forecasts with only what it knew that evening. And both apps are judged on the same days.
Forecasts are tested the same way. A cut-off is a day where we pretend to stand. The method sees only the days up to the cut-off and forecasts the days after it. Then we compare its forecast with the real sales, which we know because they are in the history. We repeat this at many cut-offs. This test is a backtest: a test on the past, done as if each cut-off were today.
The course runs every method through the same backtest, and it writes one row per method into one table:
- The same series: 50 products, with their three regions added up (
BACKTEST_PRODUCTSin the notebook). - The same cut-offs: 13 days, 28 days apart, from 13 April 2025 to 15 March 2026. At each one, the method forecasts the next 14 days: Kenji’s horizon.
- The same measures: the error, the bias, the time to fit, and the cost of Kenji’s orders, with the prices of the frame.
- Days the method may use
- The 14 days it forecasts
Text description of the chart
The chart has 13 rows, one for each cut-off, numbered from 1 at the top to 13 at the bottom. Each row has a long line from 1 April 2024 to the cut-off day: the days that the method may use. A short line follows it: the 14 days that it forecasts. The first cut-off is 13 April 2025, so its history is about one year long. Each next row starts its forecast 28 days later. The last cut-off is 15 March 2026, and its 14 days end on 29 March 2026, the last day of the history.
The cell of section 3 runs the simplest method of all: “the same weekday last week”. Before you run it, predict: in percent of the units sold, does this forecast miss by about 10%, 25% or 50%?
sales = load_sales(BACKTEST_PRODUCTS)fc = bt.backtest(sales, bt.seasonal_naive(7), h=14, origins=ORIGINS)row = bt.score(fc, sales, "seasonal naive", season=7, cost=bt.stock_cost(PRICES))table = bt.show([row])The output:
method horizon MASE WAPE % bias % pinball fit s cost $seasonal naive 14 1.034 51.3 -0.5 0.04 16739The fit s value depends on your computer. Every other value must be the same.
Read the first row
Section titled “Read the first row”Module 3 explains each measure with a worked example. For now, read them in plain words:
| Column | Value | In plain words |
|---|---|---|
method |
seasonal naive | The forecast: the same weekday of last week. “Naive” means that it learns nothing. |
horizon |
14 | It forecasts 14 days after each cut-off. |
WAPE % |
51.3 | All the misses added up are 51.3% of all the units sold. |
bias % |
−0.5 | The forecast is 0.5% too low in total. Its misses do not lean to one side. |
MASE |
1.034 | Its error compared with the error of the same method on the past days. Near 1 here, because it is that method. |
pinball |
(empty) | A score for forecast ranges. This method gives no range here. |
fit s |
0.04 | Seconds to fit, for all 13 cut-offs. |
cost $ |
16739 | The cost of Kenji’s 14-day orders made from this forecast, on average per cut-off, in dollars. |
A miss of half the units sold sounds bad. For one day of one product, it is normal, because daily sales of one product are noisy. The number means more next to other rows. Every module of this course adds rows to this table: smarter statistical methods, machine learning, a foundation model, and ranges. This first row is the line to beat. A method that costs more than 16,739 dollars per order is not worth its complexity.
Your turn: a promotion week
Section titled “Your turn: a promotion week”Change one thing in section 2. Before you run it, predict: product P141, a black duvet, had a 25% promotion from Monday 8 to Sunday 14 September 2025. Did its sales grow by a quarter, by half, or more? In a new cell, add up P141’s sales per week and print three weeks of September 2025.
Show the answer
duvet = demand[demand["product_id"] == "P141"].groupby("date")["sales"].sum()weekly = duvet.resample("W-SUN").sum()print(weekly["2025-09-01":"2025-09-21"])date2025-09-07 802025-09-14 1832025-09-21 76Freq: W-SUN, Name: sales, dtype: int64resample("W-SUN") adds the days up into weeks that end on Sunday, and pandas names each week by its Sunday. In the promotion week, the duvet sold 183, against 80 the week before and 76 the week after: more than twice as many. A price cut of 25% did much more than add 25%. The promotion is a situation we planted. It is also listed in promotions.csv in advance, so a forecast can know about it. Module 2 uses this.
Common mistake
A day that is not there
Symptom: Mei, the data engineer, says that the orders feed is complete. Section 4 of the notebook checks it:
orders = pd.read_csv("data/orders.csv", parse_dates=["date"])per_day = orders.groupby("date")["orders"].sum()all_days = pd.date_range(per_day.index.min(), per_day.index.max(), freq="D")print(len(per_day), "days with orders,", len(all_days), "days in the calendar")print("missing:", [d.date().isoformat() for d in all_days.difference(per_day.index)])727 days with orders, 728 days in the calendarmissing: ['2025-10-19']No error appears anywhere. The file has no rows for Sunday 19 October 2025. The feed dropped that day. It is a situation we planted.
Cause: a method that reads “one row per day” puts Monday 20 October straight after Saturday 18 October. Every later day is then one step off: “the same weekday last week” reads a Monday where it expects a Tuesday.
Fix: always make the series complete before you forecast. List every period from the first to the last (pd.date_range), and decide what each missing period gets. In this course, the helper load_sales() gives a missing day the mean of the same weekday one week before and one week after. For the orders, that is Sunday 12 October (695) and Sunday 26 October (592): (695 + 592) ÷ 2 = 643.5. Module 2 discusses this choice.
Consequence in AI work: a missing period breaks a forecast silently. The numbers look normal, so nobody checks. The tickets of that day are complete, so the two tables no longer agree either. In production, a missing day of data should stop the forecast, not shift it. The forecasting job of Module 8 does that.
Guided practice: run the notebook
Section titled “Guided practice: run the notebook”- Open the notebook from the box Do this lesson in a notebook at the top of this page.
- Run the three setup cells. You see
pandas 2.3.3,statsforecast 2.1.1and theReady:line. - In section 1, write your prediction: which table has the most rows. Then run the cell. You see
demand.csv.gzwith403758 rows. - In section 2, run the parasol cell. You see
727 days, 4201 parasols sold, 14 promotion days, 9 days with a stock-out, and a chart with two summers. - In the Your turn cell, count the stock-out days of P002 in the north. Put the number in
p002_north_out. - Run the check cell. It prints
Check passed: p002_north_out is 9. - In section 3, write your prediction for the miss, in percent. Then run the backtest cell. You see
seasonal naive,1.034,51.3,-0.5and16739. - In section 4, run the cell. You see
missing: ['2025-10-19']. - Add a new cell for the duvet of Your turn: a promotion week. You see
183for the week that ends on 14 September 2025.
Knowledge check
Section titled “Knowledge check”Check your understanding
The demand table has a column sales and a column stock_out, but no column with the real demand. Why does this matter for Kenji's frame, and what does the stock_out flag let you do?
Show the answer
Kenji’s frame says to forecast demand, but the data records only sales. On a stock-out day, sales are lower than demand, often zero. The real demand of those days is not in the data. The stock_out flag shows which days they are. So you can keep those days out of the training data or fill them, instead of teaching the forecast that nobody wanted the product. P002 in the north has nine such days, from 12 to 20 May 2025.
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
Predict and explain: you forecast the orders with 'the same weekday last week', and you forget the missing day of 19 October 2025. Which forecasts go wrong, and why does no error appear?
Show the answer
Without the missing row, the series puts Monday 20 October right after Saturday 18 October. A method that steps back 7 rows to find “the same weekday last week” now lands one weekday off for the days after the gap. So the forecasts of the following week use the wrong weekday. No error appears, because every row still has a date and a number. Fix it by listing every day with pd.date_range, and filling the missing day. The course’s rule takes the mean of the same weekday one week before and one week after.
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
Explain the course's backtest in your own words: what is a cut-off, what does the method see at each one, and why do all methods use the same 13 cut-offs and the same 50 products?
Show the answer
A cut-off is a day in the history where we pretend to stand. The method sees only the days up to the cut-off, and it forecasts the 14 days after it. Then we compare the forecast with the real sales of those days. The course repeats this at 13 cut-offs, 28 days apart, from 13 April 2025 to 15 March 2026. All methods use the same cut-offs and the same 50 products, so their rows can be compared fairly. It is like two weather apps judged on the same days. A method that is tested on easier days or easier products would look better than it is.
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
- The setup works when the notebook prints
Ready: 403758 rows of daily sales (200 products, 3 regions), from 2024-04-01 to 2026-03-29. - Larkfield has ten tables. Each one is a set of time series: values in time order, one per day or per hour. The order of the rows matters.
- The demand table holds sales and a
stock_outflag, not the real demand. P002 in the north had nine stock-out days in a row. - Calendar, promotions and price changes are known 13 weeks ahead. The sales of those weeks are the hidden future, kept back for the final scoring.
- One day, 19 October 2025, is missing from the sales and the orders. Make every series complete before you forecast.
- The backtest table tests every method at the same 13 cut-offs, on the same 50 products, 14 days ahead. Its first row, “same weekday last week”, misses by 51.3% of the units sold and costs 16,739 dollars per order. Every later method must beat it.
You can now open the data, read its tables and run a method through the backtest. But the parasol’s line still goes up and down, and it is hard to say why. Next, you split a series into a slow trend, a season that repeats and the rest.
Next: Trend, season and noise