Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 38 ยท Getting Started

Figure-Level vs Axes-Level Functions

Understand the key design idea in seaborn: axes-level functions draw on one Axes, figure-level functions like relplot, displot and catplot manage a whole figure.

Seaborn has two kinds of plotting functions, and mixing them up is the most common source of confusion. Axes-level functions such as scatterplot and histplot draw onto a single Matplotlib Axes. Figure-level functions such as relplot, displot and catplot create and manage a whole figure, and can split the data into a grid of subplots. Once you know which is which, the rest of the API falls into place.

The two layers

Two kinds of seaborn function

Axes-level Draws on one Axes. You choose the figure.
Figure-level Makes its own figure. Can split by col and row.

Same plot, different amount of control.

1 / 3
flowchart TD
    R["relplot (figure-level)"] --> S["scatterplot (axes-level)"]
    R --> L["lineplot (axes-level)"]
    D["displot (figure-level)"] --> H["histplot"]
    D --> K["kdeplot"]
    D --> E["ecdfplot"]
    C["catplot (figure-level)"] --> B["boxplot, violinplot, barplot, stripplot, ..."]

Each figure-level function picks one axes-level function through its kind argument.

Axes-level: you own the figure

An axes-level function draws on the current axes, or on the one you pass with ax=. It returns that Axes. Because you hold the Matplotlib objects, you can combine several plots in one figure and style them with normal Matplotlib calls.

Python Axes-level functions on shared axes

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 axes-level functions when you want to build a custom layout with plt.subplots, overlay two plots on one axes, or place a seaborn chart into a larger Matplotlib figure.

Figure-level: seaborn owns the figure

A figure-level function makes its own figure and returns a grid object (FacetGrid, JointGrid or PairGrid), not an Axes. Its big advantage is faceting: col= and row= split the data into small multiples without any loops.

Python One call, three panels

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 printout shows FacetGrid and an axes array of shape (1, 3). g.axes and g.figure give you the Matplotlib objects; g.set_axis_labels and g.set_titles are convenience methods that act on every panel.

Size works differently

This trips people up.

Axes-level Figure-level
Size set by plt.figure(figsize=...) or plt.subplots(figsize=...) height= and aspect= (size of each facet)
Place in your layout ax= Cannot be placed with ax=
Faceting No col=, row=
Legend Inside the axes Outside, on the right
Returns Axes FacetGrid / JointGrid / PairGrid
Switch type of chart Use another function kind=

With figure-level functions, height=3 and aspect=1.5 mean each panel is 3 inches tall and 4.5 inches wide. A grid with three columns is therefore 13.5 inches wide, plus the legend. Do not pass figsize to them or call plt.figure(figsize=...) beforehand; it has no effect.

Choosing between them

  • A single chart, or a custom multi-plot layout: axes-level.
  • Splitting by a categorical variable into small multiples: figure-level.
  • You need several different seaborn plots in one figure: axes-level, because figure-level functions cannot share a figure.
  • You want the quickest exploration with a legend outside the plot: figure-level.

You can always convert between them: sns.displot(kind="kde") produces the same marks as sns.kdeplot, just wrapped in a grid.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which of these is a figure-level function?

    relplot, displot and catplot are the three main figure-level functions. The others are axes-level.
  2. 2. What does an axes-level function like sns.scatterplot return?

    It returns the Axes it drew on, so you can keep customizing it with Matplotlib.
  3. 3. You call sns.catplot(..., col="day", height=3, aspect=1.5). What do height and aspect describe?

    In figure-level functions, the size is per facet. The full figure width is roughly aspect x height x number of columns.
  4. 4. You need a boxplot and a histogram side by side in one figure. Which approach fits?

    Figure-level functions create their own figure and ignore ax=. Axes-level functions can be placed on axes you create.

Summary

  • Axes-level functions (scatterplot, histplot, boxplot, ...) draw on one Axes and return it; use ax= to place them.
  • Figure-level functions (relplot, displot, catplot, plus lmplot, jointplot, pairplot) create a figure and return a grid object.
  • Figure-level functions support col= and row= faceting and choose the plot type with kind=.
  • Their size is set with height and aspect per facet, not figsize.
  • Pick axes-level for custom layouts, figure-level for small multiples.

Next: Tidy Data: Long vs Wide Tables