Figure#

Thewhole figure. The Figure keepstrack of all the childAxes, a group of'special' Artists (titles, figure legends, colorbars, etc.), andeven nested subfigures.

Typically, you'll create a new Figure through one of the followingfunctions:

fig=plt.figure()# an empty figure with no Axesfig,ax=plt.subplots()# a figure with a single Axesfig,axs=plt.subplots(2,2)# a figure with a 2x2 grid of Axes# a figure with one Axes on the left, and two on the right:fig,axs=plt.subplot_mosaic([['left','right_top'],['left','right_bottom']])

subplots() andsubplot_mosaic are convenience functionsthat additionally create Axes objects inside the Figure, but you can alsomanually add Axes later on.

For more on Figures, including panning and zooming, seeIntroduction to Figures.

Axes#

An Axes is an Artist attached to a Figure that contains a region forplotting data, and usually includes two (or three in the case of 3D)Axis objects (be aware of the differencebetweenAxes andAxis) that provide ticks and tick labels toprovide scales for the data in the Axes. EachAxes alsohas a title(set viaset_title()), an x-label (set viaset_xlabel()), and a y-label set viaset_ylabel()).

TheAxes methods are the primary interface for configuringmost parts of your plot (adding data, controlling axis scales andlimits, adding labels etc.).

Axis#

These objects set the scale and limits and generate ticks (the markson the Axis) and ticklabels (strings labeling the ticks). The locationof the ticks is determined by aLocator object and theticklabel strings are formatted by aFormatter. Thecombination of the correctLocator andFormatter gives very finecontrol over the tick locations and labels.

Artist#

Basically, everything visible on the Figure is an Artist (evenFigure,Axes, andAxis objects). This includesText objects,Line2D objects,collections objects,Patchobjects, etc. When the Figure is rendered, all of theArtists are drawn to thecanvas. Most Artists are tied to an Axes; suchan Artist cannot be shared by multiple Axes, or moved from one to another.

The explicit and the implicit interfaces#

As noted above, there are essentially two ways to use Matplotlib:

• Explicitly create Figures and Axes, and call methods on them (the"object-oriented (OO) style").

• Rely on pyplot to implicitly create and manage the Figures and Axes, anduse pyplot functions for plotting.

SeeMatplotlib Application Interfaces (APIs) for an explanation of the tradeoffs between theimplicit and explicit interfaces.

So one can use the OO-style

x=np.linspace(0,2,100)# Sample data.# Note that even in the OO-style, we use `.pyplot.figure` to create the Figure.fig,ax=plt.subplots(figsize=(5,2.7),layout='constrained')ax.plot(x,x,label='linear')# Plot some data on the Axes.ax.plot(x,x**2,label='quadratic')# Plot more data on the Axes...ax.plot(x,x**3,label='cubic')# ... and some more.ax.set_xlabel('x label')# Add an x-label to the Axes.ax.set_ylabel('y label')# Add a y-label to the Axes.ax.set_title("Simple Plot")# Add a title to the Axes.ax.legend()# Add a legend.

or the pyplot-style:

x=np.linspace(0,2,100)# Sample data.plt.figure(figsize=(5,2.7),layout='constrained')plt.plot(x,x,label='linear')# Plot some data on the (implicit) Axes.plt.plot(x,x**2,label='quadratic')# etc.plt.plot(x,x**3,label='cubic')plt.xlabel('x label')plt.ylabel('y label')plt.title("Simple Plot")plt.legend()

(In addition, there is a third approach, for the case when embeddingMatplotlib in a GUI application, which completely drops pyplot, even forfigure creation. See the corresponding section in the gallery for more info:Embedding Matplotlib in graphical user interfaces.)

Matplotlib's documentation and examples use both the OO and the pyplotstyles. In general, we suggest using the OO style, particularly forcomplicated plots, and functions and scripts that are intended to be reusedas part of a larger project. However, the pyplot style can be very convenientfor quick interactive work.

Making a helper functions#

If you need to make the same plots over and over again with different datasets, or want to easily wrap Matplotlib methods, use the recommendedsignature function below.

defmy_plotter(ax,data1,data2,param_dict):"""    A helper function to make a graph.    """out=ax.plot(data1,data2,**param_dict)returnout

which you would then use twice to populate two subplots:

data1,data2,data3,data4=np.random.randn(4,100)# make 4 random data setsfig,(ax1,ax2)=plt.subplots(1,2,figsize=(5,2.7))my_plotter(ax1,data1,data2,{'marker':'x'})my_plotter(ax2,data3,data4,{'marker':'o'})

Note that if you want to install these as a python package, or any othercustomizations you could use one of the many templates on the web;Matplotlib has one atmpl-cookiecutter

Colors#

Matplotlib has a very flexible array of colors that are accepted for mostArtists; seeallowable color definitions for alist of specifications. Some Artists will take multiple colors. i.e. forascatter plot, the edge of the markers can be different colorsfrom the interior:

fig,ax=plt.subplots(figsize=(5,2.7))ax.scatter(data1,data2,s=50,facecolor='C0',edgecolor='k')

Linewidths, linestyles, and markersizes#

Line widths are typically in typographic points (1 pt = 1/72 inch) andavailable for Artists that have stroked lines. Similarly, stroked linescan have a linestyle. See thelinestyles example.

Marker size depends on the method being used.plot specifiesmarkersize in points, and is generally the "diameter" or width of themarker.scatter specifies markersize as approximatelyproportional to the visual area of the marker. There is an array ofmarkerstyles available as string codes (seemarkers), orusers can define their ownMarkerStyle (seeMarker reference):

fig,ax=plt.subplots(figsize=(5,2.7))ax.plot(data1,'o',label='data1')ax.plot(data2,'d',label='data2')ax.plot(data3,'v',label='data3')ax.plot(data4,'s',label='data4')ax.legend()

Axes labels and text#

set_xlabel,set_ylabel, andset_title are used toadd text in the indicated locations (seeText in Matplotlibfor more discussion). Text can also be directly added to plots usingtext:

mu,sigma=115,15x=mu+sigma*np.random.randn(10000)fig,ax=plt.subplots(figsize=(5,2.7),layout='constrained')# the histogram of the datan,bins,patches=ax.hist(x,50,density=True,facecolor='C0',alpha=0.75)ax.set_xlabel('Length [cm]')ax.set_ylabel('Probability')ax.set_title('Aardvark lengths\n (not really)')ax.text(75,.025,r'$\mu=115,\ \sigma=15$')ax.axis([55,175,0,0.03])ax.grid(True)

All of thetext functions return amatplotlib.text.Textinstance. Just as with lines above, you can customize the properties bypassing keyword arguments into the text functions:

t=ax.set_xlabel('my data',fontsize=14,color='red')

These properties are covered in more detail inText properties and layout.

Using mathematical expressions in text#

Matplotlib accepts TeX equation expressions in any text expression.For example to write the expression\(\sigma_i=15\) in the title,you can write a TeX expression surrounded by dollar signs:

ax.set_title(r'$\sigma_i=15$')

where ther preceding the title string signifies that the string is araw string and not to treat backslashes as python escapes.Matplotlib has a built-in TeX expression parser andlayout engine, and ships its own math fonts – for details seeWriting mathematical expressions. You can also use LaTeX directly to formatyour text and incorporate the output directly into your display figures orsaved postscript – seeText rendering with LaTeX.

Annotations#

We can also annotate points on a plot, often by connecting an arrow pointingtoxy, to a piece of text atxytext:

fig,ax=plt.subplots(figsize=(5,2.7))t=np.arange(0.0,5.0,0.01)s=np.cos(2*np.pi*t)line,=ax.plot(t,s,lw=2)ax.annotate('local max',xy=(2,1),xytext=(3,1.5),arrowprops=dict(facecolor='black',shrink=0.05))ax.set_ylim(-2,2)

In this basic example, bothxy andxytext are in data coordinates.There are a variety of other coordinate systems one can choose -- seeBasic annotation andAdvanced annotation fordetails. More examples also can be found inAnnotate plots.

Legends#

Often we want to identify lines or markers with aAxes.legend:

fig,ax=plt.subplots(figsize=(5,2.7))ax.plot(np.arange(len(data1)),data1,label='data1')ax.plot(np.arange(len(data2)),data2,label='data2')ax.plot(np.arange(len(data3)),data3,'d',label='data3')ax.legend()

Legends in Matplotlib are quite flexible in layout, placement, and whatArtists they can represent. They are discussed in detail inLegend guide.

Scales#

In addition to the linear scale, Matplotlib supplies non-linear scales,such as a log-scale. Since log-scales are used so much there are alsodirect methods likeloglog,semilogx, andsemilogy. There are a number of scales (seeScales overview for other examples). Here we set the scalemanually:

fig,axs=plt.subplots(1,2,figsize=(5,2.7),layout='constrained')xdata=np.arange(len(data1))# make an ordinal for thisdata=10**data1axs[0].plot(xdata,data)axs[1].set_yscale('log')axs[1].plot(xdata,data)

The scale sets the mapping from data values to spacing along the Axis. Thishappens in both directions, and gets combined into atransform, whichis the way that Matplotlib maps from data coordinates to Axes, Figure, orscreen coordinates. SeeTransformations Tutorial.

Tick locators and formatters#

Each Axis has a ticklocator andformatter that choose where along theAxis objects to put tick marks. A simple interface to this isset_xticks:

fig,axs=plt.subplots(2,1,layout='constrained')axs[0].plot(xdata,data1)axs[0].set_title('Automatic ticks')axs[1].plot(xdata,data1)axs[1].set_xticks(np.arange(0,100,30),['zero','30','sixty','90'])axs[1].set_yticks([-1.5,0,1.5])# note that we don't need to specify labelsaxs[1].set_title('Manual ticks')

Different scales can have different locators and formatters; for instancethe log-scale above usesLogLocator andLogFormatter. SeeTick locators andTick formatters for other formatters andlocators and information for writing your own.

Plotting dates and strings#

Matplotlib can handle plotting arrays of dates and arrays of strings, aswell as floating point numbers. These get special locators and formattersas appropriate. For dates:

frommatplotlib.datesimportConciseDateFormatterfig,ax=plt.subplots(figsize=(5,2.7),layout='constrained')dates=np.arange(np.datetime64('2021-11-15'),np.datetime64('2021-12-25'),np.timedelta64(1,'h'))data=np.cumsum(np.random.randn(len(dates)))ax.plot(dates,data)ax.xaxis.set_major_formatter(ConciseDateFormatter(ax.xaxis.get_major_locator()))

For more information see the date examples(e.g.Date tick labels)

For strings, we get categorical plotting (see:Plotting categorical variables).

fig,ax=plt.subplots(figsize=(5,2.7),layout='constrained')categories=['turnips','rutabaga','cucumber','pumpkins']ax.bar(categories,np.random.rand(len(categories)))

One caveat about categorical plotting is that some methods of parsingtext files return a list of strings, even if the strings all representnumbers or dates. If you pass 1000 strings, Matplotlib will think youmeant 1000 categories and will add 1000 ticks to your plot!

Additional Axis objects#

Plotting data of different magnitude in one chart may requirean additional y-axis. Such an Axis can be created by usingtwinx to add a new Axes with an invisible x-axis and a y-axispositioned at the right (analogously fortwiny). SeePlots with different scales for another example.

Similarly, you can add asecondary_xaxis orsecondary_yaxis having a different scale than the main Axis torepresent the data in different scales or units. SeeSecondary Axis for furtherexamples.

fig,(ax1,ax3)=plt.subplots(1,2,figsize=(7,2.7),layout='constrained')l1,=ax1.plot(t,s)ax2=ax1.twinx()l2,=ax2.plot(t,range(len(t)),'C1')ax2.legend([l1,l2],['Sine (left)','Straight (right)'])ax3.plot(t,s)ax3.set_xlabel('Angle [rad]')ax4=ax3.secondary_xaxis('top',(np.rad2deg,np.deg2rad))ax4.set_xlabel('Angle [°]')

Colormaps#

These are all examples of Artists that derive fromScalarMappableobjects. They all can set a linear mapping betweenvmin andvmax intothe colormap specified bycmap. Matplotlib has many colormaps to choosefrom (Choosing Colormaps in Matplotlib) you can make yourown (Creating Colormaps in Matplotlib) or download asthird-party packages.

Normalizations#

Sometimes we want a non-linear mapping of the data to the colormap, asin theLogNorm example above. We do this by supplying theScalarMappable with thenorm argument instead ofvmin andvmax.More normalizations are shown atColormap normalization.

Colorbars#

Adding acolorbar gives a key to relate the color back to theunderlying data. Colorbars are figure-level Artists, and are attached toa ScalarMappable (where they get their information about the norm andcolormap) and usually steal space from a parent Axes. Placement ofcolorbars can be complex: seePlacing colorbars fordetails. You can also change the appearance of colorbars with theextend keyword to add arrows to the ends, andshrink andaspect tocontrol the size. Finally, the colorbar will have default locatorsand formatters appropriate to the norm. These can be changed as forother Axis objects.