You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
<divid="unreleased-message"> You are reading an old version of the documentation (v1.5.3). For the latest version see <ahref="/stable/">https://matplotlib.org/stable/</a></div>
<spanid="id1"></span><h1>Artist tutorial<aclass="headerlink" href="#artist-tutorial" title="Permalink to this headline">¶</a></h1>
<p>There are three layers to the matplotlib API. The
<codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.backend_bases.FigureCanvas</span></code> is the area onto which
the figure is drawn, the <codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.backend_bases.Renderer</span></code> is
the object which knows how to draw on the
<codeclass="xref py py-class docutils literal"><spanclass="pre">FigureCanvas</span></code>, and the
<aclass="reference internal" href="../api/artist_api.html#matplotlib.artist.Artist" title="matplotlib.artist.Artist"><codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.artist.Artist</span></code></a> is the object that knows how to use
a renderer to paint onto the canvas. The
<codeclass="xref py py-class docutils literal"><spanclass="pre">FigureCanvas</span></code> and
<codeclass="xref py py-class docutils literal"><spanclass="pre">Renderer</span></code> handle all the details of
talking to user interface toolkits like <aclass="reference external" href="http://www.wxpython.org">wxPython</a> or drawing languages like PostScript®, and
the <codeclass="docutils literal"><spanclass="pre">Artist</span></code> handles all the high level constructs like representing
and laying out the figure, text, and lines. The typical user will
spend 95% of his time working with the <codeclass="docutils literal"><spanclass="pre">Artists</span></code>.</p>
<p>There are two types of <codeclass="docutils literal"><spanclass="pre">Artists</span></code>: primitives and containers. The primitives
represent the standard graphical objects we want to paint onto our canvas:
the containers are places to put them (<aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.Axis" title="matplotlib.axis.Axis"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axis</span></code></a>,
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code></a> and <aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-class docutils literal"><spanclass="pre">Figure</span></code></a>). The
standard use is to create a <aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-class docutils literal"><spanclass="pre">Figure</span></code></a> instance, use
the <codeclass="docutils literal"><spanclass="pre">Figure</span></code> to create one or more <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code></a> or
<codeclass="xref py py-class docutils literal"><spanclass="pre">Subplot</span></code> instances, and use the <codeclass="docutils literal"><spanclass="pre">Axes</span></code> instance
helper methods to create the primitives. In the example below, we create a
<codeclass="docutils literal"><spanclass="pre">Figure</span></code> instance using <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.figure" title="matplotlib.pyplot.figure"><codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.pyplot.figure()</span></code></a>, which is a
convenience method for instantiating <codeclass="docutils literal"><spanclass="pre">Figure</span></code> instances and connecting them
with your user interface or drawing toolkit <codeclass="docutils literal"><spanclass="pre">FigureCanvas</span></code>. As we will
discuss below, this is not necessary – you can work directly with PostScript,
PDF Gtk+, or wxPython <codeclass="docutils literal"><spanclass="pre">FigureCanvas</span></code> instances, instantiate your <codeclass="docutils literal"><spanclass="pre">Figures</span></code>
directly and connect them yourselves – but since we are focusing here on the
<codeclass="docutils literal"><spanclass="pre">Artist</span></code> API we’ll let <aclass="reference internal" href="../api/pyplot_api.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><codeclass="xref py py-mod docutils literal"><spanclass="pre">pyplot</span></code></a> handle some of those details
<spanclass="n">ax</span><spanclass="o">=</span><spanclass="n">fig</span><spanclass="o">.</span><spanclass="n">add_subplot</span><spanclass="p">(</span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="mi">1</span><spanclass="p">)</span><spanclass="c1"># two rows, one column, first plot</span>
</pre></div>
</div>
<p>The <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code></a> is probably the most important
class in the matplotlib API, and the one you will be working with most
of the time. This is because the <codeclass="docutils literal"><spanclass="pre">Axes</span></code> is the plotting area into
which most of the objects go, and the <codeclass="docutils literal"><spanclass="pre">Axes</span></code> has many special helper
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.imshow" title="matplotlib.axes.Axes.imshow"><codeclass="xref py py-meth docutils literal"><spanclass="pre">imshow()</span></code></a>) to create the most common
<codeclass="xref py py-class docutils literal"><spanclass="pre">Image</span></code>, respectively). These helper methods
will take your data (e.g., <codeclass="docutils literal"><spanclass="pre">numpy</span></code> arrays and strings) and create
primitive <codeclass="docutils literal"><spanclass="pre">Artist</span></code> instances as needed (e.g., <codeclass="docutils literal"><spanclass="pre">Line2D</span></code>), add them to
the relevant containers, and draw them when requested. Most of you
are probably familiar with the <codeclass="xref py py-class docutils literal"><spanclass="pre">Subplot</span></code>,
which is just a special case of an <codeclass="docutils literal"><spanclass="pre">Axes</span></code> that lives on a regular
rows by columns grid of <codeclass="docutils literal"><spanclass="pre">Subplot</span></code> instances. If you want to create
an <codeclass="docutils literal"><spanclass="pre">Axes</span></code> at an arbitrary location, simply use the
<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.add_axes" title="matplotlib.figure.Figure.add_axes"><codeclass="xref py py-meth docutils literal"><spanclass="pre">add_axes()</span></code></a> method which takes a list
of <codeclass="docutils literal"><spanclass="pre">[left,</span><spanclass="pre">bottom,</span><spanclass="pre">width,</span><spanclass="pre">height]</span></code> values in 0-1 relative figure
<p>In this example, <codeclass="docutils literal"><spanclass="pre">ax</span></code> is the <codeclass="docutils literal"><spanclass="pre">Axes</span></code> instance created by the
<codeclass="docutils literal"><spanclass="pre">fig.add_subplot</span></code> call above (remember <codeclass="docutils literal"><spanclass="pre">Subplot</span></code> is just a
subclass of <codeclass="docutils literal"><spanclass="pre">Axes</span></code>) and when you call <codeclass="docutils literal"><spanclass="pre">ax.plot</span></code>, it creates a
<codeclass="docutils literal"><spanclass="pre">Line2D</span></code> instance and adds it to the <codeclass="xref py py-attr docutils literal"><spanclass="pre">Axes.lines</span></code> list. In the interactive <aclass="reference external" href="http://ipython.org/">ipython</a> session below, you can see that the
<codeclass="docutils literal"><spanclass="pre">Axes.lines</span></code> list is length one and contains the same line that was
returned by the <codeclass="docutils literal"><spanclass="pre">line,</span><spanclass="pre">=</span><spanclass="pre">ax.plot...</span></code> call:</p>
<spanclass="n">ax</span><spanclass="o">.</span><spanclass="n">lines</span><spanclass="o">.</span><spanclass="n">remove</span><spanclass="p">(</span><spanclass="n">line</span><spanclass="p">)</span><spanclass="c1"># one or the other, not both!</span>
</pre></div>
</div>
<p>The Axes also has helper methods to configure and decorate the x-axis
and y-axis tick, tick labels and axis labels:</p>
<divclass="highlight-default"><divclass="highlight"><pre><span></span><spanclass="n">xtext</span><spanclass="o">=</span><spanclass="n">ax</span><spanclass="o">.</span><spanclass="n">set_xlabel</span><spanclass="p">(</span><spanclass="s1">'my xdata'</span><spanclass="p">)</span><spanclass="c1"># returns a Text instance</span>
it passes the information on the <aclass="reference internal" href="../api/text_api.html#matplotlib.text.Text" title="matplotlib.text.Text"><codeclass="xref py py-class docutils literal"><spanclass="pre">Text</span></code></a>
instance of the <aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.XAxis" title="matplotlib.axis.XAxis"><codeclass="xref py py-class docutils literal"><spanclass="pre">XAxis</span></code></a>. Each <codeclass="docutils literal"><spanclass="pre">Axes</span></code>
instance contains an <aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.XAxis" title="matplotlib.axis.XAxis"><codeclass="xref py py-class docutils literal"><spanclass="pre">XAxis</span></code></a> and a
<aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.YAxis" title="matplotlib.axis.YAxis"><codeclass="xref py py-class docutils literal"><spanclass="pre">YAxis</span></code></a> instance, which handle the layout and
drawing of the ticks, tick labels and axis labels.</p>
<spanid="customizing-artists"></span><h2>Customizing your objects<aclass="headerlink" href="#customizing-your-objects" title="Permalink to this headline">¶</a></h2>
<p>Every element in the figure is represented by a matplotlib
<aclass="reference internal" href="../api/artist_api.html#matplotlib.artist.Artist" title="matplotlib.artist.Artist"><codeclass="xref py py-class docutils literal"><spanclass="pre">Artist</span></code></a>, and each has an extensive list of
properties to configure its appearance. The figure itself contains a
<aclass="reference internal" href="../api/patches_api.html#matplotlib.patches.Rectangle" title="matplotlib.patches.Rectangle"><codeclass="xref py py-class docutils literal"><spanclass="pre">Rectangle</span></code></a> exactly the size of the figure,
which you can use to set the background color and transparency of the
(the standard white box with black edges in the typical matplotlib
plot, has a <codeclass="docutils literal"><spanclass="pre">Rectangle</span></code> instance that determines the color,
transparency, and other properties of the Axes. These instances are
stored as member variables <codeclass="xref py py-attr docutils literal"><spanclass="pre">Figure.patch</span></code> and <codeclass="xref py py-attr docutils literal"><spanclass="pre">Axes.patch</span></code> (“Patch” is a name inherited from
MATLAB, and is a 2D “patch” of color on the figure, e.g., rectangles,
circles and polygons). Every matplotlib <codeclass="docutils literal"><spanclass="pre">Artist</span></code> has the following
properties</p>
<tableborder="1" class="docutils">
<colgroup>
<colwidth="11%" />
<colwidth="89%" />
</colgroup>
<theadvalign="bottom">
<trclass="row-odd"><thclass="head">Property</th>
<thclass="head">Description</th>
</tr>
</thead>
<tbodyvalign="top">
<trclass="row-even"><td>alpha</td>
<td>The transparency - a scalar from 0-1</td>
</tr>
<trclass="row-odd"><td>animated</td>
<td>A boolean that is used to facilitate animated drawing</td>
</tr>
<trclass="row-even"><td>axes</td>
<td>The axes that the Artist lives in, possibly None</td>
</tr>
<trclass="row-odd"><td>clip_box</td>
<td>The bounding box that clips the Artist</td>
</tr>
<trclass="row-even"><td>clip_on</td>
<td>Whether clipping is enabled</td>
</tr>
<trclass="row-odd"><td>clip_path</td>
<td>The path the artist is clipped to</td>
</tr>
<trclass="row-even"><td>contains</td>
<td>A picking function to test whether the artist contains the pick point</td>
</tr>
<trclass="row-odd"><td>figure</td>
<td>The figure instance the artist lives in, possibly None</td>
</tr>
<trclass="row-even"><td>label</td>
<td>A text label (e.g., for auto-labeling)</td>
</tr>
<trclass="row-odd"><td>picker</td>
<td>A python object that controls object picking</td>
</tr>
<trclass="row-even"><td>transform</td>
<td>The transformation</td>
</tr>
<trclass="row-odd"><td>visible</td>
<td>A boolean whether the artist should be drawn</td>
</tr>
<trclass="row-even"><td>zorder</td>
<td>A number which determines the drawing order</td>
</tr>
<trclass="row-odd"><td>rasterized</td>
<td>Boolean; Turns vectors into rastergraphics: (for compression & eps transparency)</td>
</tr>
</tbody>
</table>
<p>Each of the properties is accessed with an old-fashioned setter or
getter (yes we know this irritates Pythonistas and we plan to support
direct access via properties or traits but it hasn’t been done yet).
For example, to multiply the current alpha by a half:</p>
<p>If you are working interactively at the python shell, a handy way to
inspect the <codeclass="docutils literal"><spanclass="pre">Artist</span></code> properties is to use the
<aclass="reference internal" href="../api/artist_api.html#matplotlib.artist.getp" title="matplotlib.artist.getp"><codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.artist.getp()</span></code></a> function (simply
<codeclass="xref py py-func docutils literal"><spanclass="pre">getp()</span></code> in pylab), which lists the properties
and their values. This works for classes derived from <codeclass="docutils literal"><spanclass="pre">Artist</span></code> as
well, e.g., <codeclass="docutils literal"><spanclass="pre">Figure</span></code> and <codeclass="docutils literal"><spanclass="pre">Rectangle</span></code>. Here are the <codeclass="docutils literal"><spanclass="pre">Figure</span></code> rectangle
<spanclass="go"> window_extent = <Bbox object at 0x134acbcc></span>
<spanclass="go"> x = 0</span>
<spanclass="go"> y = 0</span>
<spanclass="go"> zorder = 1</span>
</pre></div>
</div>
<p>The docstrings for all of the classes also contain the <codeclass="docutils literal"><spanclass="pre">Artist</span></code>
properties, so you can consult the interactive “help” or the
<aclass="reference internal" href="../api/artist_api.html#artist-api"><spanclass="std std-ref">artists</span></a> for a listing of properties for a given object.</p>
</div>
<divclass="section" id="object-containers">
<spanid="id2"></span><h2>Object containers<aclass="headerlink" href="#object-containers" title="Permalink to this headline">¶</a></h2>
<p>Now that we know how to inspect and set the properties of a given
object we want to configure, we need to now how to get at that object.
As mentioned in the introduction, there are two kinds of objects:
primitives and containers. The primitives are usually the things you
want to configure (the font of a <aclass="reference internal" href="../api/text_api.html#matplotlib.text.Text" title="matplotlib.text.Text"><codeclass="xref py py-class docutils literal"><spanclass="pre">Text</span></code></a>
instance, the width of a <aclass="reference internal" href="../api/lines_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><codeclass="xref py py-class docutils literal"><spanclass="pre">Line2D</span></code></a>) although
the containers also have some properties as well – for example the
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code></a><aclass="reference internal" href="../api/artist_api.html#matplotlib.artist.Artist" title="matplotlib.artist.Artist"><codeclass="xref py py-class docutils literal"><spanclass="pre">Artist</span></code></a> is a
container that contains many of the primitives in your plot, but it
also has properties like the <codeclass="docutils literal"><spanclass="pre">xscale</span></code> to control whether the xaxis
is ‘linear’ or ‘log’. In this section we’ll review where the various
container objects store the <codeclass="docutils literal"><spanclass="pre">Artists</span></code> that you want to get at.</p>
</div>
<divclass="section" id="figure-container">
<spanid="id3"></span><h2>Figure container<aclass="headerlink" href="#figure-container" title="Permalink to this headline">¶</a></h2>
<p>The top level container <codeclass="docutils literal"><spanclass="pre">Artist</span></code> is the
<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.figure.Figure</span></code></a>, and it contains everything in the
figure. The background of the figure is a
<aclass="reference internal" href="../api/patches_api.html#matplotlib.patches.Rectangle" title="matplotlib.patches.Rectangle"><codeclass="xref py py-class docutils literal"><spanclass="pre">Rectangle</span></code></a> which is stored in
<codeclass="xref py py-attr docutils literal"><spanclass="pre">Figure.patch</span></code>. As
you add subplots (<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.add_subplot" title="matplotlib.figure.Figure.add_subplot"><codeclass="xref py py-meth docutils literal"><spanclass="pre">add_subplot()</span></code></a>) and
axes (<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.add_axes" title="matplotlib.figure.Figure.add_axes"><codeclass="xref py py-meth docutils literal"><spanclass="pre">add_axes()</span></code></a>) to the figure
these will be appended to the <aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.axes" title="matplotlib.figure.Figure.axes"><codeclass="xref py py-attr docutils literal"><spanclass="pre">Figure.axes</span></code></a>. These are also returned by the
<spanclass="go">[<matplotlib.axes.Subplot instance at 0xd54b26c>, <matplotlib.axes.Axes instance at 0xd3f0b2c>]</span>
</pre></div>
</div>
<p>Because the figure maintains the concept of the “current axes” (see
<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.gca" title="matplotlib.figure.Figure.gca"><codeclass="xref py py-meth docutils literal"><spanclass="pre">Figure.gca</span></code></a> and
<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.sca" title="matplotlib.figure.Figure.sca"><codeclass="xref py py-meth docutils literal"><spanclass="pre">Figure.sca</span></code></a>) to support the
pylab/pyplot state machine, you should not insert or remove axes
directly from the axes list, but rather use the
<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.add_subplot" title="matplotlib.figure.Figure.add_subplot"><codeclass="xref py py-meth docutils literal"><spanclass="pre">add_subplot()</span></code></a> and
<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.add_axes" title="matplotlib.figure.Figure.add_axes"><codeclass="xref py py-meth docutils literal"><spanclass="pre">add_axes()</span></code></a> methods to insert, and the
<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.delaxes" title="matplotlib.figure.Figure.delaxes"><codeclass="xref py py-meth docutils literal"><spanclass="pre">delaxes()</span></code></a> method to delete. You are
free however, to iterate over the list of axes or index into it to get
access to <codeclass="docutils literal"><spanclass="pre">Axes</span></code> instances you want to customize. Here is an
<p>The figure also has its own text, lines, patches and images, which you
can use to add primitives directly. The default coordinate system for
the <codeclass="docutils literal"><spanclass="pre">Figure</span></code> will simply be in pixels (which is not usually what you
want) but you can control this by setting the transform property of
the <codeclass="docutils literal"><spanclass="pre">Artist</span></code> you are adding to the figure.</p>
<p>More useful is “figure coordinates” where (0, 0) is the bottom-left of
the figure and (1, 1) is the top-right of the figure which you can
obtain by setting the <codeclass="docutils literal"><spanclass="pre">Artist</span></code> transform to <codeclass="xref py py-attr docutils literal"><spanclass="pre">fig.transFigure</span></code>:</p>
<td>A list of Axes instances (includes Subplot)</td>
</tr>
<trclass="row-odd"><td>patch</td>
<td>The Rectangle background</td>
</tr>
<trclass="row-even"><td>images</td>
<td>A list of FigureImages patches - useful for raw pixel display</td>
</tr>
<trclass="row-odd"><td>legends</td>
<td>A list of Figure Legend instances (different from Axes.legends)</td>
</tr>
<trclass="row-even"><td>lines</td>
<td>A list of Figure Line2D instances (rarely used, see Axes.lines)</td>
</tr>
<trclass="row-odd"><td>patches</td>
<td>A list of Figure patches (rarely used, see Axes.patches)</td>
</tr>
<trclass="row-even"><td>texts</td>
<td>A list Figure Text instances</td>
</tr>
</tbody>
</table>
</div>
<divclass="section" id="axes-container">
<spanid="id4"></span><h2>Axes container<aclass="headerlink" href="#axes-container" title="Permalink to this headline">¶</a></h2>
<p>The <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.axes.Axes</span></code></a> is the center of the matplotlib
universe – it contains the vast majority of all the <codeclass="docutils literal"><spanclass="pre">Artists</span></code> used
in a figure with many helper methods to create and add these
<codeclass="docutils literal"><spanclass="pre">Artists</span></code> to itself, as well as helper methods to access and
customize the <codeclass="docutils literal"><spanclass="pre">Artists</span></code> it contains. Like the
<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-class docutils literal"><spanclass="pre">Figure</span></code></a>, it contains a
<codeclass="xref py py-attr docutils literal"><spanclass="pre">patch</span></code> which is a
<aclass="reference internal" href="../api/patches_api.html#matplotlib.patches.Rectangle" title="matplotlib.patches.Rectangle"><codeclass="xref py py-class docutils literal"><spanclass="pre">Rectangle</span></code></a> for Cartesian coordinates and a
<aclass="reference internal" href="../api/patches_api.html#matplotlib.patches.Circle" title="matplotlib.patches.Circle"><codeclass="xref py py-class docutils literal"><spanclass="pre">Circle</span></code></a> for polar coordinates; this patch
determines the shape, background and border of the plotting region:</p>
<spanclass="n">rect</span><spanclass="o">=</span><spanclass="n">ax</span><spanclass="o">.</span><spanclass="n">patch</span><spanclass="c1"># a Rectangle instance</span>
<p>When you call a plotting method, e.g., the canonical
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.plot" title="matplotlib.axes.Axes.plot"><codeclass="xref py py-meth docutils literal"><spanclass="pre">plot()</span></code></a> and pass in arrays or lists of
values, the method will create a <aclass="reference internal" href="../api/lines_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><codeclass="xref py py-meth docutils literal"><spanclass="pre">matplotlib.lines.Line2D()</span></code></a>
instance, update the line with all the <codeclass="docutils literal"><spanclass="pre">Line2D</span></code> properties passed as
keyword arguments, add the line to the <codeclass="xref py py-attr docutils literal"><spanclass="pre">Axes.lines</span></code> container, and returns it to you:</p>
<spanclass="go">[<matplotlib.lines.Line2D instance at 0xd378b0c>]</span>
</pre></div>
</div>
<p>Similarly, methods that create patches, like
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.bar" title="matplotlib.axes.Axes.bar"><codeclass="xref py py-meth docutils literal"><spanclass="pre">bar()</span></code></a> creates a list of rectangles, will
add the patches to the <codeclass="xref py py-attr docutils literal"><spanclass="pre">Axes.patches</span></code> list:</p>
<p>You should not add objects directly to the <codeclass="docutils literal"><spanclass="pre">Axes.lines</span></code> or
<codeclass="docutils literal"><spanclass="pre">Axes.patches</span></code> lists unless you know exactly what you are doing,
because the <codeclass="docutils literal"><spanclass="pre">Axes</span></code> needs to do a few things when it creates and adds
an object. It sets the figure and axes property of the <codeclass="docutils literal"><spanclass="pre">Artist</span></code>, as
well as the default <codeclass="docutils literal"><spanclass="pre">Axes</span></code> transformation (unless a transformation
is set). It also inspects the data contained in the <codeclass="docutils literal"><spanclass="pre">Artist</span></code> to
update the data structures controlling auto-scaling, so that the view
limits can be adjusted to contain the plotted data. You can,
nonetheless, create objects yourself and add them directly to the
<codeclass="docutils literal"><spanclass="pre">Axes</span></code> using helper methods like
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.add_line" title="matplotlib.axes.Axes.add_line"><codeclass="xref py py-meth docutils literal"><spanclass="pre">add_line()</span></code></a> and
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.add_patch" title="matplotlib.axes.Axes.add_patch"><codeclass="xref py py-meth docutils literal"><spanclass="pre">add_patch()</span></code></a>. Here is an annotated
interactive session illustrating what is going on:</p>
<p>In addition to all of these <codeclass="docutils literal"><spanclass="pre">Artists</span></code>, the <codeclass="docutils literal"><spanclass="pre">Axes</span></code> contains two
important <codeclass="docutils literal"><spanclass="pre">Artist</span></code> containers: the <aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.XAxis" title="matplotlib.axis.XAxis"><codeclass="xref py py-class docutils literal"><spanclass="pre">XAxis</span></code></a>
and <aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.YAxis" title="matplotlib.axis.YAxis"><codeclass="xref py py-class docutils literal"><spanclass="pre">YAxis</span></code></a>, which handle the drawing of the
ticks and labels. These are stored as instance variables
<codeclass="xref py py-attr docutils literal"><spanclass="pre">xaxis</span></code> and
<codeclass="xref py py-attr docutils literal"><spanclass="pre">yaxis</span></code>. The <codeclass="docutils literal"><spanclass="pre">XAxis</span></code> and <codeclass="docutils literal"><spanclass="pre">YAxis</span></code>
containers will be detailed below, but note that the <codeclass="docutils literal"><spanclass="pre">Axes</span></code> contains
many helper methods which forward calls on to the
<aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.Axis" title="matplotlib.axis.Axis"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axis</span></code></a> instances so you often do not need to
work with them directly unless you want to. For example, you can set
the font size of the <codeclass="docutils literal"><spanclass="pre">XAxis</span></code> ticklabels using the <codeclass="docutils literal"><spanclass="pre">Axes</span></code> helper
<spanid="axis-container"></span><h2>Axis containers<aclass="headerlink" href="#axis-containers" title="Permalink to this headline">¶</a></h2>
<p>The <aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.Axis" title="matplotlib.axis.Axis"><codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.axis.Axis</span></code></a> instances handle the drawing of the
tick lines, the grid lines, the tick labels and the axis label. You
can configure the left and right ticks separately for the y-axis, and
the upper and lower ticks separately for the x-axis. The <codeclass="docutils literal"><spanclass="pre">Axis</span></code>
also stores the data and view intervals used in auto-scaling, panning
and zooming, as well as the <aclass="reference internal" href="../api/ticker_api.html#matplotlib.ticker.Locator" title="matplotlib.ticker.Locator"><codeclass="xref py py-class docutils literal"><spanclass="pre">Locator</span></code></a> and
<aclass="reference internal" href="../api/ticker_api.html#matplotlib.ticker.Formatter" title="matplotlib.ticker.Formatter"><codeclass="xref py py-class docutils literal"><spanclass="pre">Formatter</span></code></a> instances which control where
the ticks are placed and how they are represented as strings.</p>
(this is what <codeclass="xref py py-mod docutils literal"><spanclass="pre">pylab</span></code> modifies in calls to
<codeclass="xref py py-func docutils literal"><spanclass="pre">xlabel()</span></code> and <codeclass="xref py py-func docutils literal"><spanclass="pre">ylabel()</span></code>) as well
which contain the actual line and text primitives that render the ticks and
ticklabels. Because the ticks are dynamically created as needed (e.g., when
panning and zooming), you should access the lists of major and minor ticks
through their accessor methods <aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.Axis.get_major_ticks" title="matplotlib.axis.Axis.get_major_ticks"><codeclass="xref py py-meth docutils literal"><spanclass="pre">get_major_ticks()</span></code></a>
and <aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.Axis.get_minor_ticks" title="matplotlib.axis.Axis.get_minor_ticks"><codeclass="xref py py-meth docutils literal"><spanclass="pre">get_minor_ticks()</span></code></a>. Although the ticks contain
all the primitives and will be covered below, the <codeclass="docutils literal"><spanclass="pre">Axis</span></code> methods contain
accessor methods to return the tick lines, tick labels, tick locations etc.:</p>
<spanclass="n">rect</span><spanclass="o">=</span><spanclass="n">fig</span><spanclass="o">.</span><spanclass="n">patch</span><spanclass="c1"># a rectangle instance</span>
<spanid="tick-container"></span><h2>Tick containers<aclass="headerlink" href="#tick-containers" title="Permalink to this headline">¶</a></h2>
<p>The <aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.Tick" title="matplotlib.axis.Tick"><codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.axis.Tick</span></code></a> is the final container object in our
descent from the <aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-class docutils literal"><spanclass="pre">Figure</span></code></a> to the
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></code></a> to the <aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.Axis" title="matplotlib.axis.Axis"><codeclass="xref py py-class docutils literal"><spanclass="pre">Axis</span></code></a>
to the <aclass="reference internal" href="../api/axis_api.html#matplotlib.axis.Tick" title="matplotlib.axis.Tick"><codeclass="xref py py-class docutils literal"><spanclass="pre">Tick</span></code></a>. The <codeclass="docutils literal"><spanclass="pre">Tick</span></code> contains the tick
and grid line instances, as well as the label instances for the upper
and lower ticks. Each of these is accessible directly as an attribute
of the <codeclass="docutils literal"><spanclass="pre">Tick</span></code>. In addition, there are boolean variables that determine
whether the upper labels and ticks are on for the x-axis and whether
the right labels and ticks are on for the y-axis.</p>