Figure container#

The top level containerArtist is thematplotlib.figure.Figure, and it contains everything in thefigure. The background of the figure is aRectangle which is stored inFigure.patch. Asyou add subplots (add_subplot()) andAxes (add_axes()) to the figurethese will be appended to theFigure.axes. These are also returned by themethods that create them:

In [156]:fig=plt.figure()In [157]:ax1=fig.add_subplot(211)In [158]:ax2=fig.add_axes((0.1,0.1,0.7,0.3))In [159]:ax1Out[159]:<Axes:>In [160]:print(fig.axes)[<Axes:>, <matplotlib.axes._axes.Axes object at 0x7f0768702be0>]

Because the figure maintains the concept of the "current Axes" (seeFigure.gca andFigure.sca) to support thepylab/pyplot state machine, you should not insert or remove Axesdirectly from the Axes list, but rather use theadd_subplot() andadd_axes() methods to insert, and theAxes.remove method to delete. You arefree however, to iterate over the list of Axes or index into it to getaccess toAxes instances you want to customize. Here is anexample which turns all the Axes grids on:

foraxinfig.axes:ax.grid(True)

The figure also has its ownimages,lines,patches andtextattributes, which you can use to add primitives directly. When doing so, thedefault coordinate system for theFigure will simply be in pixels (whichis not usually what you want). If you instead use Figure-level methods to addArtists (e.g., usingFigure.text to add text), then the default coordinatesystem will be "figure coordinates" where (0, 0) is the bottom-left of thefigure and (1, 1) is the top-right of the figure.

As with allArtists, you can control this coordinate system by settingthe transform property. You can explicitly use "figure coordinates" bysetting theArtist transform tofig.transFigure:

importmatplotlib.linesaslinesfig=plt.figure()l1=lines.Line2D([0,1],[0,1],transform=fig.transFigure,figure=fig)l2=lines.Line2D([0,1],[1,0],transform=fig.transFigure,figure=fig)fig.lines.extend([l1,l2])plt.show()

Here is a summary of the Artists the Figure contains

Axes container#

Thematplotlib.axes.Axes is the center of the Matplotlibuniverse -- it contains the vast majority of all theArtists usedin a figure with many helper methods to create and add theseArtists to itself, as well as helper methods to access andcustomize theArtists it contains. Like theFigure, it contains aPatchmatplotlib.axes.Axes.patch which is aRectangle for Cartesian coordinates and aCircle for polar coordinates; this patchdetermines the shape, background and border of the plotting region:

ax=fig.add_subplot()rect=ax.patch# a Rectangle instancerect.set_facecolor('green')

When you call a plotting method, e.g., the canonicalplot and pass in arrays or lists of values, themethod will create amatplotlib.lines.Line2D instance, update the line withall theLine2D properties passed as keyword arguments, add the line totheAxes, and return it to you:

In [213]:x,y=np.random.rand(2,100)In [214]:line,=ax.plot(x,y,'-',color='blue',linewidth=2)

plot returns a list of lines because you can pass in multiple x, ypairs to plot, and we are unpacking the first element of the lengthone list into the line variable. The line has been added to theAxes.lines list:

In [229]:print(ax.lines)[<matplotlib.lines.Line2D at 0xd378b0c>]

Similarly, methods that create patches, likebar() creates a list of rectangles, willadd the patches to theAxes.patches list:

In [233]:n,bins,rectangles=ax.hist(np.random.randn(1000),50)In [234]:rectanglesOut[234]:<BarContainer object of 50 artists>In [235]:print(len(ax.patches))Out[235]:50

You should not add objects directly to theAxes.lines orAxes.patcheslists, because theAxes needs to do a few things when it creates and addsan object:

• It sets thefigure andaxes property of theArtist;

• It sets the defaultAxes transformation (unless one is already set);

• It inspects the data contained in theArtist to update the datastructures controlling auto-scaling, so that the view limits can beadjusted to contain the plotted data.

You can, nonetheless, create objects yourself and add them directly to theAxes using helper methods likeadd_line andadd_patch. Here is an annotated interactive sessionillustrating what is going on:

In [262]:fig,ax=plt.subplots()# create a rectangle instanceIn [263]:rect=matplotlib.patches.Rectangle((1,1),width=5,height=12)# by default the Axes instance is NoneIn [264]:print(rect.axes)None# and the transformation instance is set to the "identity transform"In [265]:print(rect.get_data_transform())IdentityTransform()# now we add the Rectangle to the AxesIn [266]:ax.add_patch(rect)# and notice that the ax.add_patch method has set the Axes# instanceIn [267]:print(rect.axes)Axes(0.125,0.1;0.775x0.8)# and the transformation has been set tooIn [268]:print(rect.get_data_transform())CompositeGenericTransform(    TransformWrapper(        BlendedAffine2D(            IdentityTransform(),            IdentityTransform())),    CompositeGenericTransform(        BboxTransformFrom(            TransformedBbox(                Bbox(x0=0.0, y0=0.0, x1=1.0, y1=1.0),                TransformWrapper(                    BlendedAffine2D(                        IdentityTransform(),                        IdentityTransform())))),        BboxTransformTo(            TransformedBbox(                Bbox(x0=0.125, y0=0.10999999999999999, x1=0.9, y1=0.88),                BboxTransformTo(                    TransformedBbox(                        Bbox(x0=0.0, y0=0.0, x1=6.4, y1=4.8),                        Affine2D(                            [[100.   0.   0.]                             [  0. 100.   0.]                             [  0.   0.   1.]])))))))# the default Axes transformation is ax.transDataIn [269]:print(ax.transData)CompositeGenericTransform(    TransformWrapper(        BlendedAffine2D(            IdentityTransform(),            IdentityTransform())),    CompositeGenericTransform(        BboxTransformFrom(            TransformedBbox(                Bbox(x0=0.0, y0=0.0, x1=1.0, y1=1.0),                TransformWrapper(                    BlendedAffine2D(                        IdentityTransform(),                        IdentityTransform())))),        BboxTransformTo(            TransformedBbox(                Bbox(x0=0.125, y0=0.10999999999999999, x1=0.9, y1=0.88),                BboxTransformTo(                    TransformedBbox(                        Bbox(x0=0.0, y0=0.0, x1=6.4, y1=4.8),                        Affine2D(                            [[100.   0.   0.]                             [  0. 100.   0.]                             [  0.   0.   1.]])))))))# notice that the xlimits of the Axes have not been changedIn [270]:print(ax.get_xlim())(0.0, 1.0)# but the data limits have been updated to encompass the rectangleIn [271]:print(ax.dataLim.bounds)(1.0, 1.0, 5.0, 12.0)# we can manually invoke the auto-scaling machineryIn [272]:ax.autoscale_view()# and now the xlim are updated to encompass the rectangle, plus marginsIn [273]:print(ax.get_xlim())(0.75, 6.25)# we have to manually force a figure drawIn [274]:fig.canvas.draw()

There are many, manyAxes helper methods for creating primitiveArtists and adding them to their respective containers. The tablebelow summarizes a small sampling of them, the kinds ofArtist theycreate, and where they store them

In addition to all of theseArtists, theAxes contains twoimportantArtist containers: theXAxisandYAxis, which handle the drawing of theticks and labels. These are stored as instance variablesmatplotlib.axes.Axes.xaxis andmatplotlib.axes.Axes.yaxis. TheXAxis andYAxiscontainers will be detailed below, but note that theAxes containsmany helper methods which forward calls on to theAxis instances, so you often do not need towork with them directly unless you want to. For example, you can setthe font color of theXAxis ticklabels using theAxes helpermethod:

ax.tick_params(axis='x',labelcolor='orange')

Below is a summary of the Artists that theAxes contains

The legend can be accessed byget_legend,

Axis containers#

Thematplotlib.axis.Axis instances handle the drawing of thetick lines, the grid lines, the tick labels and the axis label. Youcan configure the left and right ticks separately for the y-axis, andthe upper and lower ticks separately for the x-axis. TheAxisalso stores the data and view intervals used in auto-scaling, panningand zooming, as well as theLocator andFormatter instances which control wherethe ticks are placed and how they are represented as strings.

EachAxis object contains alabel attribute(this is whatpyplot modifies in calls toxlabel andylabel) as well as a list of major and minor ticks. The ticks areaxis.XTick andaxis.YTick instances, which contain the actual line andtext primitives that render the ticks and ticklabels. Because the ticks aredynamically created as needed (e.g., when panning and zooming), you shouldaccess the lists of major and minor ticks through their accessor methodsaxis.Axis.get_major_ticks andaxis.Axis.get_minor_ticks. Althoughthe ticks contain all the primitives and will be covered below,Axisinstances have accessor methods that return the tick lines, tick labels, ticklocations etc.:

fig,ax=plt.subplots()axis=ax.xaxisaxis.get_ticklocs()

array([0. , 0.2, 0.4, 0.6, 0.8, 1. ])

axis.get_ticklabels()

[Text(0.0, 0, '0.0'), Text(0.2, 0, '0.2'), Text(0.4, 0, '0.4'), Text(0.6000000000000001, 0, '0.6'), Text(0.8, 0, '0.8'), Text(1.0, 0, '1.0')]

note there are twice as many ticklines as labels because by default there aretick lines at the top and bottom but only tick labels below the xaxis;however, this can be customized.

axis.get_ticklines()

<a list of 12 Line2D ticklines objects>

And with the above methods, you only get lists of major ticks back bydefault, but you can also ask for the minor ticks:

axis.get_ticklabels(minor=True)axis.get_ticklines(minor=True)

<a list of 0 Line2D ticklines objects>

Here is a summary of some of the useful accessor methods of theAxis(these have corresponding setters where useful, such asset_major_formatter().)

Here is an example, not recommended for its beauty, which customizesthe Axes and Tick properties.

# plt.figure creates a matplotlib.figure.Figure instancefig=plt.figure()rect=fig.patch# a rectangle instancerect.set_facecolor('lightgoldenrodyellow')ax1=fig.add_axes((0.1,0.3,0.4,0.4))rect=ax1.patchrect.set_facecolor('lightslategray')forlabelinax1.xaxis.get_ticklabels():# label is a Text instancelabel.set_color('red')label.set_rotation(45)label.set_fontsize(16)forlineinax1.yaxis.get_ticklines():# line is a Line2D instanceline.set_color('green')line.set_markersize(25)line.set_markeredgewidth(3)plt.show()

Tick containers#

Thematplotlib.axis.Tick is the final container object in ourdescent from theFigure to theAxes to theAxisto theTick. TheTick contains the tickand grid line instances, as well as the label instances for the upperand lower ticks. Each of these is accessible directly as an attributeof theTick.

Here is an example which sets the formatter for the right side ticks withdollar signs and colors them green on the right side of the yaxis.

importmatplotlib.pyplotaspltimportnumpyasnp# Fixing random state for reproducibilitynp.random.seed(19680801)fig,ax=plt.subplots()ax.plot(100*np.random.rand(20))# Use automatic StrMethodFormatterax.yaxis.set_major_formatter('${x:1.2f}')ax.yaxis.set_tick_params(which='major',labelcolor='green',labelleft=False,labelright=True)plt.show()

Total running time of the script: (0 minutes 1.274 seconds)

Gallery generated by Sphinx-Gallery