The explicit "Axes" interface#

The "Axes" interface is how Matplotlib is implemented, and many customizationsand fine-tuning end up being done at this level.

This interface works by instantiating an instance of aFigure class (fig below), using asubplots method (or similar) on that object to create one or moreAxes objects (ax below), and then calling drawingmethods on the Axes (plot in this example):

importmatplotlib.pyplotaspltfig=plt.figure()ax=fig.subplots()ax.plot([1,2,3,4],[0,0.5,1,0.2])

(Sourcecode,2x.png,png)

We call this an "explicit" interface because each object is explicitlyreferenced, and used to make the next object. Keeping references to the objectsis very flexible, and allows us to customize the objects after they are created,but before they are displayed.

The implicit "pyplot" interface#

Thepyplot module shadows most of theAxes plotting methods to give the equivalent ofthe above, where the creation of the Figure and Axes is done for the user:

importmatplotlib.pyplotaspltplt.plot([1,2,3,4],[0,0.5,1,0.2])

(Sourcecode,2x.png,png)

This can be convenient, particularly when doing interactive work or simplescripts. A reference to the current Figure can be retrieved usinggcf and to the current Axes bygca. Thepyplot moduleretains a list of Figures, and each Figure retains a list of Axes on the figurefor the user so that the following:

importmatplotlib.pyplotaspltplt.subplot(1,2,1)plt.plot([1,2,3],[0,0.5,0.2])plt.subplot(1,2,2)plt.plot([3,2,1],[0,0.5,0.2])

(Sourcecode,2x.png,png)

is equivalent to:

importmatplotlib.pyplotaspltplt.subplot(1,2,1)ax=plt.gca()ax.plot([1,2,3],[0,0.5,0.2])plt.subplot(1,2,2)ax=plt.gca()ax.plot([3,2,1],[0,0.5,0.2])

(Sourcecode,2x.png,png)

In the explicit interface, this would be:

importmatplotlib.pyplotaspltfig,axs=plt.subplots(1,2)axs[0].plot([1,2,3],[0,0.5,0.2])axs[1].plot([3,2,1],[0,0.5,0.2])

(Sourcecode,2x.png,png)

Translating between the Axes interface and the pyplot interface#

You may find either interface in existing code, and unfortunately sometimes evenmixtures. This section describes the patterns for specific operations in bothinterfaces and how to translate from one to the other.

• Creating figures is the same for both interfaces: Use the respectivepyplotfunctionsplt.figure(),plt.subplots(),plt.subplot_mosaic().For the Axes interface, you typically store the created Figure (and possiblyAxes) in variables for later use. When using the pyplot interface, thesevalues are typically not stored. Example:

  • Axes:fig,ax=plt.subplots()

  • pyplot:plt.subplots()

• "Plotting" functions, i.e. functions that add data, are named the same andhave identical parameters on the Axes and in pyplot. Example:

  • Axes:ax.plot(x,y)

  • pyplot:plt.plot(x,y)

• Functions that retrieve properties are named like the property in pyplotand are prefixed withget_ on the Axes. Example:

  • Axes:label=ax.get_xlabel()

  • pyplot:label=plt.xlabel()

• Functions that set properties like the property in pyplot and are prefixed withset_ on the Axes. Example:

  • Axes:ax.set_xlabel("time")

  • pyplot:plt.xlabel("time")

Here is a short summary of the examples again as a side-by-side comparison:

Why be explicit?#

What happens if you have to backtrack, and operate on an old axes that is notreferenced byplt.gca()? One simple way is to callsubplot again withthe same arguments. However, that quickly becomes inelegant. You can alsoinspect the Figure object and get its list of Axes objects, however, that can bemisleading (colorbars are Axes too!). The best solution is probably to save ahandle to every Axes you create, but if you do that, why not simply create theall the Axes objects at the start?

The first approach is to callplt.subplot again:

importmatplotlib.pyplotaspltplt.subplot(1,2,1)plt.plot([1,2,3],[0,0.5,0.2])plt.subplot(1,2,2)plt.plot([3,2,1],[0,0.5,0.2])plt.suptitle('Implicit Interface: re-call subplot')foriinrange(1,3):plt.subplot(1,2,i)plt.xlabel('Boo')

(Sourcecode,2x.png,png)

The second is to save a handle:

importmatplotlib.pyplotaspltaxs=[]ax=plt.subplot(1,2,1)axs+=[ax]plt.plot([1,2,3],[0,0.5,0.2])ax=plt.subplot(1,2,2)axs+=[ax]plt.plot([3,2,1],[0,0.5,0.2])plt.suptitle('Implicit Interface: save handles')foriinrange(2):plt.sca(axs[i])plt.xlabel('Boo')

(Sourcecode,2x.png,png)

However, the recommended way would be to be explicit from the outset:

importmatplotlib.pyplotaspltfig,axs=plt.subplots(1,2)axs[0].plot([1,2,3],[0,0.5,0.2])axs[1].plot([3,2,1],[0,0.5,0.2])fig.suptitle('Explicit Interface')foriinrange(2):axs[i].set_xlabel('Boo')

(Sourcecode,2x.png,png)