Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 57 ยท Getting Started

Anatomy of a Figure

Learn the names of every part of a Matplotlib chart: Figure, Axes, Axis, ticks, spines, legend and Artists, and why Axes is not the same as axis.

Matplotlib's documentation, error messages and Stack Overflow answers all use a small vocabulary: Figure, Axes, Axis, Artist, tick, spine. Once you know which word names which part, the library stops feeling random. This lesson draws a chart, then takes it apart piece by piece, using code that prints the objects so you can see them.

Pay special attention to Axes versus Axis. They look like singular and plural of the same word. They are not.

The parts of a chart

The container

Figure The whole canvas. Holds everything.
Axes One plot area inside the Figure.

A Figure can hold one Axes or many.

1 / 3

Figure: the canvas

The Figure is the outermost container: the page everything is drawn on. It has a size, a background color, and a list of Axes. It can also hold things that belong to no single plot, such as an overall title (fig.suptitle) or a legend for the whole figure.

Axes: one plot

An Axes is one plot: the rectangle with data, a coordinate system, and its own title and labels. This is where you call plot, bar, scatter and hist. Despite the plural-looking name, one Axes is a single plot. A Figure with four subplots holds four Axes objects.

Axis: the number line

An Axis is one number line: the x axis or the y axis. It draws the ticks and their labels and decides where they go (locators) and how they look (formatters). An Axes has two Axis objects: ax.xaxis and ax.yaxis. A 3D Axes has three.

The mnemonic: Axes is the plot, Axis is the line of numbers on its edge. Most methods you use daily live on Axes (ax.set_xlabel, ax.set_xlim) even though they affect an Axis. Methods on the Axis itself appear when you tune ticks, as in Ticks, Locators and Formatters.

Python Taking a figure apart

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 output shows one Axes in the Figure, two Axis objects, one line, four spines named left, right, bottom and top, and the tick positions that Matplotlib chose automatically.

Ticks, labels and spines

A tick is a small mark on an axis at a value, and a tick label is the text beside it. Ticks come in two kinds: major (long, labelled) and minor (short, usually unlabelled and off by default).

Spines are the four lines that frame the data area. You can hide the top and right ones for a cleaner look, move the others to cross at zero, or color them. They are plain Artists, so they can be styled like any line.

Python Restyling the parts

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.

You changed spines, tick positions and tick label size without touching the data. That separation, data on one side and decoration on the other, is the heart of Matplotlib's design.

Everything is an Artist

Matplotlib has a single base class, Artist, for anything that can be drawn: the Figure, each Axes, each Axis, every line, text string, rectangle, tick and spine. Artists form a tree.

flowchart TD
    F["Figure"] --> A["Axes"]
    A --> X["xaxis"]
    A --> Y["yaxis"]
    A --> S["spines"]
    A --> L["Line2D, Text, Patch..."]
    X --> T["ticks and tick labels"]

The Figure owns Axes; each Axes owns Axis objects, spines and the data artists.

When you call ax.plot, Matplotlib creates a Line2D artist and adds it to the Axes. When you call ax.set_title, it sets a Text artist. When the figure is rendered, the renderer asks the Figure to draw itself, the Figure asks each Axes, and so on down the tree. Because of this you can reach any part: ax.lines[0] is the line, ax.title is the title text, ax.xaxis.label is the x label.

Python Walking the artist tree

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.

You grabbed an artist that already existed and changed it. Most "set" calls are really that: fetch an artist, change one property. The same property system is why ax.plot(..., color="red") and line.set_color("red") mean the same thing. See Transforms and the Artist Layer for the deep end.

Many beginners write plt.axis(...) when they mean something about the Axes, or call a plot "the axis". Say "Axes" for the plot, "axis" for the x or y line, and error messages and docs will make sense.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In Matplotlib vocabulary, what is an Axes?

    An Axes is one plot: it holds the data artists, the coordinate system, and its own Axis objects. The Figure is the whole canvas.
  2. 2. How many Axis objects does an ordinary 2D Axes have?

    A 2D Axes has an x Axis and a y Axis (ax.xaxis, ax.yaxis). Spines are separate artists.
  3. 3. What are spines?

    Spines are the left, right, top and bottom border lines of the Axes. They can be hidden, moved or colored.
  4. 4. What does ax.plot(x, y) create and add to the Axes?

    Plotting creates a Line2D artist and adds it to ax.lines. Because it is an Artist, you can change its properties later.

Summary

  • The Figure is the canvas; an Axes is one plot inside it; an Axis is the x or y number line of an Axes.
  • Ticks (major and minor) mark positions on an Axis; tick labels are their text; spines are the four border lines.
  • Everything drawable is an Artist, arranged in a tree: Figure, Axes, Axis, ticks, lines, text, patches.
  • Plotting creates artists; styling is mostly fetching an artist and changing a property.
  • Remember: Axes is the plot, Axis is the number line.

Next, see the two ways to drive all of this in pyplot vs the Object-Oriented API.