Matplotlib · Chapter 11 of 16
Annotation and direct labels
By the end of this chapter you can put words on a chart where they belong: text at a point in the data with ax.text, a note in a corner that stays put with transform=ax.transAxes, an arrow at a peak with ax.annotate, names at the ends of lines instead of a legend, a shaded period or band with ax.axvspan and ax.axhspan, and a title that states the finding, with every number in it computed from the data. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Many charts
- 4 tasks
- Matplotlib
- In the all labs plan
The first 2 chapters of Matplotlib are free. This one comes with the all labs plan.
Why you need this
Ira's monthly report to the housing societies opens with Delhi's autumn: 61 days of PM2.5, October and November 2025, with India's 24-hour standard of 60 µg/m³ drawn across it. You can draw that chart already. A treasurer in Mayur Vihar looks at it and asks three questions: what is the grey line, what was the worst day, and was it Diwali? All three answers are in the data. None of them is on the chart.
<!-- chart: !Delhi's daily PM2.5 in October and November 2025, a grey line at 60, a sharp peak at the end of October, and no words at all -->
A chart that makes the reader work out the finding fails Ira's five-second test. Everything in the last ten chapters makes the shape right; this chapter adds the words that say what the shape means, on the chart itself, next to the thing they are about.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
peak_note.py: point at the peak
Write peak_chart(hours, pm25, site) in peak_note.py. hours is a list of whole hours (0 to 23) and pm25 a list of one station's readings at those hours, from diwali_hourly.csv; site is the station's place. It makes a new Figure and Axes, draws pm25 against hours as one line, and annotates the highest reading: one annotation, with an arrow, pointing at the point (its hour, its value) on the line, whose words are exactly Peak <value> at <hour>:00, the value with one decimal place and the hour with two digits (Peak 412.0 at 21:00, Peak 96.5 at 07:00). It returns the Figure, with exactly one Axes and one line.
The Check tries Rohini Sector 9 on Diwali (20 October 2025), Saket on 16 October and the three hours [6, 7, 8] with [71.2, 96.5, 80.4], so find the peak and its hour from the lists.
- Task 2
city_labels.py: name the lines where they end
Write labelled_cities(days, by_city) in city_labels.py. days is a list of day numbers (1 to 30 for November) and by_city a dict from city_daily.csv that maps each city's name to a list of its daily PM2.5 on those days. It makes a new Figure and Axes and, for each city in the dict, draws its readings against days as one line and puts the city's name (the dict's key; spaces around it are fine) as text at the end of that line: y is the line's last reading, and x is the last day or a little to the right of it (up to a tenth of the days' span), in data coordinates. Each name is drawn in its own line's colour. The chart has no legend. It returns the Figure, with exactly one Axes and one line per city.
The Check tries the five cities in November 2025 and three cities (Ghaziabad, Delhi, Gurugram) in July 2026, 31 days.
- Task 3
outage.py: shade the outage and say so
Write outage_chart(times, pm25) in outage.py. times is a pandas Series of hourly datetimes from delhi_hourly.csv, and pm25 a Series of the readings at those times, NaN where SaafHawa's server was down (both with the index 0, 1, 2 ...). It makes a new Figure and Axes and:
- draws pm25 against times as one line, with the blanks kept (the line breaks at the gap: do not drop them);
- shades the outage with one band across the chart (ax.axvspan) from the first blank hour to the last blank hour;
- writes a note in axes coordinates (transform=ax.transAxes, with x and y between 0 and 1) whose words are exactly Server down for <n> hours, where n is the number of blank hours.
It returns the Figure, with exactly one Axes and one line. The Check tries 13 to 16 January 2026 (the real outage) and 1 to 3 February 2026 with a shorter gap of its own, so find the gap from the blanks in pm25.
- Task 4 · interview question
Interview: claim_title.py, a title that tells the truth
Ira's night_chart(hours, diwali, normal) draws one station's readings from 18:00 to 23:00 on Diwali night (diwali) and on a normal night (normal) as two lines, under a title on the left that states the finding. It was right for Punjabi Bagh; for Mayur Vihar its title says the same number. Fix it so the title is right for any station: on the left, exactly Diwali night was <times> times a normal night, where times is the mean of diwali divided by the mean of normal (the means as they are, not rounded), shown with one decimal place. It returns the Figure, with exactly one Axes and the two lines.
The Check tries Punjabi Bagh, Mayur Vihar and Anand Vihar, 18:00 to 23:00 on 20 and on 16 October 2025.
Tanvir will ask: why must the numbers on a chart be computed from the data and never typed in?
What you will learn
- ax.text(x, y, s): words at a place in the data.
- ha, va, fontsize: how words sit on their point, and how big.
- transform=ax.transAxes: a place on the chart from 0 to 1, which stays put whatever the data.
- ax.annotate(text, xy=, xytext=, arrowprops=): words with an arrow pointing at a point.
- Direct labels: each line's name at its end, in its colour, instead of a legend.
- ax.axvspan and ax.axhspan: a shaded period on x, or a band on y.
- The title is the claim: loc="left", with numbers from the data in an f-string.
More in Many charts
Build "Annotation and direct labels" yourself
SaafHawa runs air sensors across Delhi NCR. Principals, societies and investors need its numbers at a glance: you draw them. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of Matplotlib are free. This one comes with the all labs plan.