Introduction to Axes (or Subplots)#
MatplotlibAxes are the gateway to creating your data visualizations.Once an Axes is placed on a figure there are many methods that can be used toadd data to the Axes. An Axes typically has a pair ofAxisArtists that define the data coordinate system, and include methods to addannotations like x- and y-labels, titles, and legends.
Anatomy of a Figure#
In the picture above, the Axes object was created withax=fig.subplots().Everything else on the figure was created with methods on thisax object,or can be accessed from it. If we want to change the label on the x-axis, wecallax.set_xlabel('NewLabel'), if we want to plot some data we callax.plot(x,y). Indeed, in the figure above, the only Artist that is notpart of the Axes is the Figure itself, so theaxes.Axes class is really thegateway to much of Matplotlib's functionality.
Note that Axes are so fundamental to the operation of Matplotlib that a lot ofmaterial here is duplicate of that inQuick start guide.
Creating Axes#
importmatplotlib.pyplotaspltimportnumpyasnpfig,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...forrowinrange(2):forcolinrange(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 onFigure objects, or via thepyplot interface. These methods are discussed in more detail inCreating Figures andArranging multiple Axes in a Figure. However, for instanceadd_axes will manually position an Axes on the page. In the example abovesubplots put a grid of subplots on the figure, andaxs 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 anAxes that fills the whole figure.pyplot.subplotsandFigure.subplots: add a grid of Axes as in the exampleabove. The pyplot version returns both the Figure object and an array ofAxes. Note thatfig,ax=plt.subplots()adds a single Axes to a Figure.pyplot.subplot_mosaicandFigure.subplot_mosaic: add a grid of namedAxes and return a dictionary of axes. Forfig,axs=plt.subplot_mosaic([['left','right'],['bottom','bottom']]),axs['left']is an Axes in the top row on the left, andaxs['bottom']is an Axes that spans both columns on the bottom.
SeeArranging multiple Axes in a Figure for more detail on how to arrange grids of Axes on aFigure.
Axes plotting methods#
Most of the high-level plotting methods are accessed from theaxes.Axesclass. See the API documentation for a full curated list, andPlot types for examples. A basic example isaxes.Axes.plot:
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 thatplot returns a list oflines Artists which can subsequently bemanipulated, as discussed inIntroduction to Artists.
A very incomplete list of plotting methods is below. Again, seePlot typesfor more examples, andaxes.Axes for the full list of methods.
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. TheAxes class has a number of methods to create these annotations.
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 ofText properties and layout that can be set on the text objects, likefontsize,fontname,horizontalalignment. Legends can be much more complicated; seeLegend guide for more details.
Note that text can also be added to axes usingtext, andannotate. This can be quite sophisticated: seeText properties and layout andAnnotations for more information.
Axes limits, scales, and ticking#
Each Axes has two (or more)Axis objects, that can be accessed viamatplotlib.axes.Axes.xaxis andmatplotlib.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 atAxis. However, the Axes class offers a number of helpers for the most common of these methods. Indeed, theset_xlabel, discussed above, is a helper for theset_label_text.
Other important methods set the extent on the axes (set_xlim,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:
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 isset_xticks andset_yticks which manually set the tick locations and optionally their labels. Minor ticks can be toggled withminorticks_on orminorticks_off.
Many aspects of Axes ticks and tick labeling can be adjusted usingtick_params. For instance, to label the top of the axes instead of the bottom,color the ticks red, and color the ticklabels green:
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 withset_aspect:
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')
