Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 57 ยท Annotation and Polish

Annotations and Arrows

Guide the reader's eye with ax.annotate, arrowprops, coordinate systems, axhline, axvline, axvspan, boxed text and direct labels on the last point.

A chart that shows the data is good. A chart that also says what to notice is better. Annotations are the words, arrows and highlighted regions that point at the interesting part: the peak, the turning point, the threshold, the event that explains a dip. Done well, they replace a paragraph of explanation and let the title carry the message.

This lesson covers ax.annotate with arrows, the coordinate systems that decide where text lands, reference lines and shaded spans, text with a background box, and direct labels at the end of a line. It follows Titles, Labels, Text and Math.

Four annotation tools

annotate Text plus an arrow to a point.
Reference lines axhline and axvline mark a level.
Spans axvspan shades a range.
text Free text, optionally boxed.

Annotate the one thing the reader should notice.

1 / 2

ax.annotate with an arrow

ax.annotate("label", xy=(x, y), xytext=(tx, ty), arrowprops=...) writes the text at xytext and, when you pass arrowprops, draws an arrow ending at xy. The point xy is the target; xytext is where the words sit. Without arrowprops you get only text.

Python Highlight a peak

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Compute the target from the data, as the code does with np.argmax. Hard-coding the position breaks the moment the data change.

arrowprops is a dictionary. With arrowstyle you pick a head ("->", "-|>", "<->", "simple", "fancy"). Without arrowstyle, Matplotlib draws a simpler arrow and accepts width, headwidth and shrink. Use connectionstyle="arc3,rad=0.3" to curve the arrow, and shrinkA and shrinkB to leave a gap at the text and at the target.

Coordinate systems

By default both xy and xytext are in data coordinates. The text moves if the axes are rescaled, which is what you want when pointing at data. Other systems are chosen with xycoords (for the target) and textcoords (for the text):

Value Meaning
"data" Data values (default for xy)
"axes fraction" 0 to 1 across the Axes, regardless of data
"figure fraction" 0 to 1 across the whole figure
"offset points" Points away from the target xy
"offset pixels" Pixels away from the target

"offset points" is the most useful for labels: "put this text 20 points up and to the right of the point" stays correct however the chart is scaled.

Python Offsets and axes fractions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The footnote uses xy=(1, 0) in axes fractions, which is the bottom-right corner. Then xytext=(-6, 6) offsets it a little inward. That is the recommended way to place source notes or logos.

Reference lines and spans

Not every annotation is an arrow. Often you need a line at a threshold or a shaded range:

  • ax.axhline(y) draws a horizontal line across the whole Axes, and ax.axvline(x) a vertical one.
  • ax.axhspan(ymin, ymax) and ax.axvspan(xmin, xmax) shade a band.
  • ax.hlines and ax.vlines draw lines with explicit extents.

These use data coordinates along one axis and span the whole Axes along the other, so they keep working when the user zooms.

Python A threshold and a highlighted event

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Use alpha so the span does not hide the data, and keep reference lines thinner and quieter than the data line. Give spans a label if they belong in the legend.

Text with a background box

ax.text(x, y, "words", bbox=dict(...)) puts a rounded or square box behind the text. A bbox with a white face and some transparency keeps text readable on top of busy data. Remember that ax.text takes data coordinates by default; pass transform=ax.transAxes to use fractions of the Axes instead.

Python A boxed note in the corner

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Label the last point instead of using a legend

For a few lines, a legend forces the reader to look back and forth. Writing each series' name at its last point is faster to read. Use annotate with a small offset, and color the text like the line.

Python Direct labels at the end of lines

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The extra x range on the right gives the labels space. Labels at line ends can collide when lines finish close together; nudge the offsets or sort the values and spread the y positions apart.

Rules of thumb

  • Annotate one to three things per chart. More turns the chart into clutter.
  • Put the message in the title ("Sales dipped after the price rise") and let the annotation show where.
  • Compute positions from the data, and prefer offset points for label offsets.
  • Keep annotation colors quieter than the data, except for the single highlight.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In ax.annotate('peak', xy=(3, 5), xytext=(1, 6), arrowprops=dict(arrowstyle='->')), which point does the arrow end at?

    xy is the target the arrow points at, and xytext is where the text sits. The arrow runs from the text to xy.
  2. 2. Which textcoords value places a label 10 points above its target regardless of scaling?

    'offset points' measures from the xy target in typographic points, so the label keeps its distance when the axes are rescaled.
  3. 3. How do you shade the x range from 30 to 35 across the full height of the Axes?

    axvspan shades a vertical band between two x values over the whole Axes height. axhspan does the same for y.
  4. 4. What does transform=ax.transAxes change for ax.text?

    With transAxes, (0, 0) is the bottom-left and (1, 1) the top-right of the Axes, so the text stays in place when data limits change.

Summary

  • ax.annotate(text, xy=, xytext=, arrowprops=) writes text and draws an arrow to a target.
  • xycoords and textcoords choose the coordinate system: data, axes fraction, figure fraction, offset points.
  • axhline, axvline, axhspan and axvspan mark thresholds and ranges.
  • ax.text(..., bbox=dict(...)) adds a readable box; transform=ax.transAxes pins text to the Axes.
  • Label the last point of each line directly instead of using a legend when there are few lines.
  • Annotate sparingly and compute positions from the data.

Next, draw your own shapes in Shapes, Patches and Custom Drawing.