DataPie tutorials

Hands-on tutorials for DataPie, the Python package for time series and data management in macroeconomic modelling. They are written for an economist who knows basic Python and has never used DataPie.

The reference documentation answers "what does this method do?", class by class. These tutorials answer "how do I do X?", task by task, easiest first, and cover the part of the package you will use every day. Where the two overlap, the tutorials link to the reference instead of repeating it.

Written and tested against DataPie 0.8.0 (Python 3.14, Windows 11).

The tutorials

The tutorials sit in three folders under tutorials, one for each group below. Read them in the order listed here: each one starts where the previous one ends, and none assumes anything beyond the tutorials before it. Every tutorial takes 30 to 35 minutes.

Foundations: one series at a time · tutorials/foundations

Tutorial	By the end you will
Time periods and spans	lay out the calendar of a forecast round: sample, horizon, months and dates
Your first time series	hold GDP as a series, read and write any stretch of it, compute with it
Lags, logs and moving averages	compute lags, log-growth, averages over time and moving windows
Growth rates and cumulations	produce q/q, y/y, annualised and year-to-date rates, contributions, projections
Charts	draw levels, growth bars, stacked contributions, dashboards and scatters

Preparing data: the transformations before any analysis · tutorials/preparing-data

Tutorial	By the end you will
Changing frequency	aggregate daily and monthly data, interpolate annual data into quarters
Gaps, splices and extensions	fill gaps, splice data vintages without breaks, extend series
Trends and smoothing	estimate an output gap with the HP filter and its relatives
Seasonal adjustment	seasonally adjust with X13 and handle the ways it fails

Working at scale: many paths, many series, many charts · tutorials/working-at-scale

Tutorial	By the end you will
Scenarios and draws: variants	hold scenarios and simulations in one series and draw a fan chart
Databoxes	manage a dataset in one container, transform and check it in bulk
Files in and out	read and write CSV, pickle and JSON, including other people's files
Chartpacks	describe a chart book once and redraw it for every data release

Running the tutorials

Each tutorial is a MyST Markdown file that jupytext turns into a notebook:

pip install datapie==0.8.0 jupytext ipykernel
jupytext --to ipynb tutorials/foundations/01-periods-and-spans.md

Then open tutorials/foundations/01-periods-and-spans.ipynb in JupyterLab, VS Code or any other notebook front end, and run it from the folder it is in.

A few things to know before you start:

• The "⚠️ Break it" cells fail on purpose. They are tagged raises-exception, so jupyter nbconvert --execute runs straight through them, but "Run All" in JupyterLab stops at the first one. Run them one at a time; that is the point of them.
• Files in and out writes files into tutorials/working-at-scale/tutorial-12-files/. Delete the folder whenever you like.
• Seasonal adjustment on Windows: the X13 program that DataPie 0.8.0 ships for Windows can crash on quarterly series. The tutorial explains the symptom and includes a small helper that works around it.
• The data in the tutorials are made up, generated in the notebooks themselves, so every tutorial runs offline and on its own.

How each tutorial is built

Every tutorial has the same eight parts, in the same order, so you always know where to look:

Part	What it holds
Title and header line	time needed, what to read first, what comes next
"By the end you will…"	one concrete outcome
Setup cell	the same imports and settings in every tutorial
Sections	one idea each, prose first, then code
⚠️ Break it	2–4 deliberate mistakes: the mistake, the message, what it means
What you did	the whole tutorial as a cheat sheet
Things to remember	3–5 points, only the ones that bite
Next	links forward, and one exercise with an answer to check against

Conventions for contributors

• One tutorial is one file, named NN-short-slug.md (two digits, hyphens, lower case), in the folder of its group. The number only sets the reading order: tutorials cite each other by title, as a relative link, never by number.
• Headings carry no numbers. To point to a section or a Break-it example, name its heading in italics.
• Everything stays in the main flow: no collapsible <details> blocks and no hidden cells. The answer to the exercise follows the exercise directly.
• One topic per tutorial, covered completely; traps are explained where the reader first meets them, not on a separate page.
• Code goes in {code-cell} ipython3 cells. Cells that fail on purpose carry :tags: [raises-exception].
• An output quoted in the prose, as a text block right after a cell, must be exactly what that cell prints.
• .ipynb files are generated and never committed: notebook JSON does not diff, and stored outputs go stale.