Introduction to Axes (or Subplots)

Matplotlib ~.axes.Axes are the gateway to creating your data visualizations. Once an Axes is placed on a figure there are many methods that can be used to add data to the Axes. An Axes typically has a pair of ~.axis.Axis Artists that define the data coordinate system, and include methods to add annotations like x- and y-labels, titles, and legends.

Anatomy of a Figure

In the picture above, the Axes object was created with ax = fig.subplots(). Everything else on the figure was created with methods on this ax object, or can be accessed from it. If we want to change the label on the x-axis, we call ax.set_xlabel('New Label'), if we want to plot some data we call ax.plot(x, y). Indeed, in the figure above, the only Artist that is not part of the Axes is the Figure itself, so the .axes.Axes class is really the gateway to much of Matplotlib's functionality.

Note that Axes are so fundamental to the operation of Matplotlib that a lot of material here is duplicate of that in :ref:`quick_start`.

Creating Axes

.. plot::
    :include-source:

    import matplotlib.pyplot as plt
    import numpy as np

    fig, axs = plt.subplots(ncols=2, nrows=2, figsize=(3.5, 2.5),
                            layout="constrained")
    # for each Axes, add an artist, in this case a nice label in the middle...
    for row in range(2):
        for col in range(2):
            axs[row, col].annotate(f'axs[{row}, {col}]', (0.5, 0.5),
                                transform=axs[row, col].transAxes,
                                ha='center', va='center', fontsize=18,
                                color='darkgrey')
    fig.suptitle('plt.subplots()')

Axes are added using methods on ~.Figure objects, or via the ~.pyplot interface. These methods are discussed in more detail in :ref:`creating_figures` and :doc:`arranging_axes`. However, for instance ~.Figure.add_axes will manually position an Axes on the page. In the example above ~.pyplot.subplots put a grid of subplots on the figure, and axs is a (2, 2) array of Axes, each of which can have data added to them.

There are a number of other methods for adding Axes to a Figure:

• .Figure.add_axes: manually position an Axes. fig.add_axes((0, 0, 1, 1)) makes an Axes that fills the whole figure.
• .pyplot.subplots and .Figure.subplots: add a grid of Axes as in the example above. The pyplot version returns both the Figure object and an array of Axes. Note that fig, ax = plt.subplots() adds a single Axes to a Figure.
• .pyplot.subplot_mosaic and .Figure.subplot_mosaic: add a grid of named Axes and return a dictionary of axes. For fig, axs = plt.subplot_mosaic([['left', 'right'], ['bottom', 'bottom']]), axs['left'] is an Axes in the top row on the left, and axs['bottom'] is an Axes that spans both columns on the bottom.

See :doc:`arranging_axes` for more detail on how to arrange grids of Axes on a Figure.

Axes plotting methods

Most of the high-level plotting methods are accessed from the .axes.Axes class. See the API documentation for a full curated list, and :ref:`plot_types` for examples. A basic example is .axes.Axes.plot:

.. plot::
    :include-source:

    fig, ax = plt.subplots(figsize=(4, 3))
    np.random.seed(19680801)
    t = np.arange(100)
    x = np.cumsum(np.random.randn(100))
    lines = ax.plot(t, x)

Note that plot returns a list of lines Artists which can subsequently be manipulated, as discussed in :ref:`users_artists`.

A very incomplete list of plotting methods is below. Again, see :ref:`plot_types` for more examples, and .axes.Axes for the full list of methods.

:ref:`basic_plots`	~.axes.Axes.plot, ~.axes.Axes.scatter, ~.axes.Axes.bar, ~.axes.Axes.step,
:ref:`arrays`	~.axes.Axes.pcolormesh, ~.axes.Axes.contour, ~.axes.Axes.quiver, ~.axes.Axes.streamplot, ~.axes.Axes.imshow
:ref:`stats_plots`	~.axes.Axes.hist, ~.axes.Axes.errorbar, ~.axes.Axes.hist2d, ~.axes.Axes.pie, ~.axes.Axes.boxplot, ~.axes.Axes.violinplot
:ref:`unstructured_plots`	~.axes.Axes.tricontour, ~.axes.Axes.tripcolor

Axes labelling and annotation

Usually we want to label the Axes with an xlabel, ylabel, and title, and often we want to have a legend to differentiate plot elements. The ~.axes.Axes class has a number of methods to create these annotations.

.. plot::
    :include-source:

    fig, ax = plt.subplots(figsize=(5, 3), layout='constrained')
    np.random.seed(19680801)
    t = np.arange(200)
    x = np.cumsum(np.random.randn(200))
    y = np.cumsum(np.random.randn(200))
    linesx = ax.plot(t, x, label='Random walk x')
    linesy = ax.plot(t, y, label='Random walk y')

    ax.set_xlabel('Time [s]')
    ax.set_ylabel('Distance [km]')
    ax.set_title('Random walk example')
    ax.legend()

These methods are relatively straight-forward, though there are a number of :ref:`text_props` that can be set on the text objects, like fontsize, fontname, horizontalalignment. Legends can be much more complicated; see :ref:`legend_guide` for more details.

Note that text can also be added to axes using ~.axes.Axes.text, and ~.axes.Axes.annotate. This can be quite sophisticated: see :ref:`text_props` and :ref:`annotations` for more information.

Axes limits, scales, and ticking

Each Axes has two (or more) ~.axis.Axis objects, that can be accessed via :attr:`!matplotlib.axes.Axes.xaxis` and :attr:`!matplotlib.axes.Axes.yaxis` properties. These have substantial number of methods on them, and for highly customizable Axis-es it is useful to read the API at ~.axis.Axis. However, the Axes class offers a number of helpers for the most common of these methods. Indeed, the ~.axes.Axes.set_xlabel, discussed above, is a helper for the ~.Axis.set_label_text.

Other important methods set the extent on the axes (~.axes.Axes.set_xlim, ~.axes.Axes.set_ylim), or more fundamentally the scale of the axes. So for instance, we can make an Axis have a logarithmic scale, and zoom in on a sub-portion of the data:

.. plot::
    :include-source:

    fig, ax = plt.subplots(figsize=(4, 2.5), layout='constrained')
    np.random.seed(19680801)
    t = np.arange(200)
    x = 2**np.cumsum(np.random.randn(200))
    linesx = ax.plot(t, x)
    ax.set_yscale('log')
    ax.set_xlim(20, 180)

The Axes class also has helpers to deal with Axis ticks and their labels. Most straight-forward is ~.axes.Axes.set_xticks and ~.axes.Axes.set_yticks which manually set the tick locations and optionally their labels. Minor ticks can be toggled with ~.axes.Axes.minorticks_on or ~.axes.Axes.minorticks_off.

Many aspects of Axes ticks and tick labeling can be adjusted using ~.axes.Axes.tick_params. For instance, to label the top of the axes instead of the bottom,color the ticks red, and color the ticklabels green:

.. plot::
    :include-source:

    fig, ax = plt.subplots(figsize=(4, 2.5))
    ax.plot(np.arange(10))
    ax.tick_params(top=True, labeltop=True, color='red', axis='x',
                   labelcolor='green')

More fine-grained control on ticks, setting scales, and controlling the Axis can be highly customized beyond these Axes-level helpers.

Axes layout

Sometimes it is important to set the aspect ratio of a plot in data space, which we can do with ~.axes.Axes.set_aspect:

.. plot::
    :include-source:

    fig, axs = plt.subplots(ncols=2, figsize=(7, 2.5), layout='constrained')
    np.random.seed(19680801)
    t = np.arange(200)
    x = np.cumsum(np.random.randn(200))
    axs[0].plot(t, x)
    axs[0].set_title('aspect="auto"')

    axs[1].plot(t, x)
    axs[1].set_aspect(3)
    axs[1].set_title('aspect=3')