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.3.1). For the latest version see <ahref="https://matplotlib.org/stable/faq/howto_faq.html">https://matplotlib.org/stable/faq/howto_faq.html</a></div>
<li><aclass="reference internal" href="#save-multiple-plots-to-one-pdf-file">Save multiple plots to one pdf file</a></li>
<li><aclass="reference internal" href="#move-the-edge-of-an-axes-to-make-room-for-tick-labels">Move the edge of an axes to make room for tick labels</a></li>
<li><aclass="reference internal" href="#automatically-make-room-for-tick-labels">Automatically make room for tick labels</a></li>
<li><aclass="reference internal" href="#configure-the-tick-linewidths">Configure the tick linewidths</a></li>
<li><aclass="reference internal" href="#align-my-ylabels-across-multiple-subplots">Align my ylabels across multiple subplots</a></li>
<li><aclass="reference internal" href="#skip-dates-where-there-is-no-data">Skip dates where there is no data</a></li>
<li><aclass="reference internal" href="#test-whether-a-point-is-inside-a-polygon">Test whether a point is inside a polygon</a></li>
<li><aclass="reference internal" href="#control-the-depth-of-plot-elements">Control the depth of plot elements</a></li>
<li><aclass="reference internal" href="#make-the-aspect-ratio-for-plots-equal">Make the aspect ratio for plots equal</a></li>
<li><aclass="reference internal" href="#make-a-movie">Make a movie</a></li>
<li><aclass="reference internal" href="#find-all-objects-in-a-figure-of-a-certain-type" id="id3">Find all objects in a figure of a certain type</a></li>
<li><aclass="reference internal" href="#save-multiple-plots-to-one-pdf-file" id="id5">Save multiple plots to one pdf file</a></li>
<li><aclass="reference internal" href="#move-the-edge-of-an-axes-to-make-room-for-tick-labels" id="id6">Move the edge of an axes to make room for tick labels</a></li>
<li><aclass="reference internal" href="#automatically-make-room-for-tick-labels" id="id7">Automatically make room for tick labels</a></li>
<li><aclass="reference internal" href="#configure-the-tick-linewidths" id="id8">Configure the tick linewidths</a></li>
<li><aclass="reference internal" href="#align-my-ylabels-across-multiple-subplots" id="id9">Align my ylabels across multiple subplots</a></li>
<li><aclass="reference internal" href="#skip-dates-where-there-is-no-data" id="id10">Skip dates where there is no data</a></li>
<li><aclass="reference internal" href="#test-whether-a-point-is-inside-a-polygon" id="id11">Test whether a point is inside a polygon</a></li>
<li><aclass="reference internal" href="#control-the-depth-of-plot-elements" id="id12">Control the depth of plot elements</a></li>
<li><aclass="reference internal" href="#make-the-aspect-ratio-for-plots-equal" id="id13">Make the aspect ratio for plots equal</a></li>
<li><aclass="reference internal" href="#make-a-movie" id="id14">Make a movie</a></li>
<li><aclass="reference internal" href="#generate-images-without-having-a-window-appear" id="id16">Generate images without having a window appear</a></li>
<spanid="howto-findobj"></span><h3>Find all objects in a figure of a certain type<aclass="headerlink" href="#find-all-objects-in-a-figure-of-a-certain-type" title="Permalink to this headline">¶</a></h3>
<p>Every matplotlib artist (see <aclass="reference internal" href="../users/artists.html#artist-tutorial"><em>Artist tutorial</em></a>) has a method
called <aclass="reference internal" href="../api/artist_api.html#matplotlib.artist.Artist.findobj" title="matplotlib.artist.Artist.findobj"><ttclass="xref py py-meth docutils literal"><spanclass="pre">findobj()</span></tt></a> that can be used to
recursively search the artist for any artists it may contain that meet
some criteria (eg match all <aclass="reference internal" href="../api/artist_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><ttclass="xref py py-class docutils literal"><spanclass="pre">Line2D</span></tt></a>
instances or match some arbitrary filter function). For example, the
following snippet finds every object in the figure which has a
<ttclass="xref py py-obj docutils literal"><spanclass="pre">set_color</span></tt> property and makes the object blue:</p>
<spanid="howto-transparent"></span><h3>Save transparent figures<aclass="headerlink" href="#save-transparent-figures" title="Permalink to this headline">¶</a></h3>
<p>The <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.savefig" title="matplotlib.pyplot.savefig"><ttclass="xref py py-meth docutils literal"><spanclass="pre">savefig()</span></tt></a> command has a keyword argument
<em>transparent</em> which, if ‘True’, will make the figure and axes
backgrounds transparent when saving, but will not affect the displayed
image on the screen.</p>
<p>If you need finer grained control, eg you do not want full transparency
or you want to affect the screen displayed version as well, you can set
<spanid="howto-multipage"></span><h3>Save multiple plots to one pdf file<aclass="headerlink" href="#save-multiple-plots-to-one-pdf-file" title="Permalink to this headline">¶</a></h3>
<p>Many image file formats can only have one image per file, but some
formats support multi-page files. Currently only the pdf backend has
support for this. To make a multi-page pdf file, first initialize the
<p>You can give the <aclass="reference internal" href="../api/backend_pdf_api.html#matplotlib.backends.backend_pdf.PdfPages" title="matplotlib.backends.backend_pdf.PdfPages"><ttclass="xref py py-class docutils literal"><spanclass="pre">PdfPages</span></tt></a>
object to <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.savefig" title="matplotlib.pyplot.savefig"><ttclass="xref py py-func docutils literal"><spanclass="pre">savefig()</span></tt></a>, but you have to specify
<spanid="howto-subplots-adjust"></span><h3>Move the edge of an axes to make room for tick labels<aclass="headerlink" href="#move-the-edge-of-an-axes-to-make-room-for-tick-labels" title="Permalink to this headline">¶</a></h3>
<p>For subplots, you can control the default spacing on the left, right,
bottom, and top as well as the horizontal and vertical spacing between
multiple rows and columns using the
<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.subplots_adjust" title="matplotlib.figure.Figure.subplots_adjust"><ttclass="xref py py-meth docutils literal"><spanclass="pre">matplotlib.figure.Figure.subplots_adjust()</span></tt></a> method (in pyplot it
is <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.subplots_adjust" title="matplotlib.pyplot.subplots_adjust"><ttclass="xref py py-func docutils literal"><spanclass="pre">subplots_adjust()</span></tt></a>). For example, to move
the bottom of the subplots up to make room for some rotated x tick
<p>You can control the defaults for these parameters in your
<ttclass="file docutils literal"><spanclass="pre">matplotlibrc</span></tt> file; see <aclass="reference internal" href="../users/customizing.html#customizing-matplotlib"><em>Customizing matplotlib</em></a>. For
example, to make the above setting permanent, you would set:</p>
<divclass="highlight-python"><pre>figure.subplot.bottom : 0.2 # the bottom of the subplots of the figure</pre>
</div>
<p>The other parameters you can configure are, with their defaults</p>
<dlclass="docutils">
<dt><em>left</em> = 0.125</dt>
<dd>the left side of the subplots of the figure</dd>
<dt><em>right</em> = 0.9</dt>
<dd>the right side of the subplots of the figure</dd>
<dt><em>bottom</em> = 0.1</dt>
<dd>the bottom of the subplots of the figure</dd>
<dt><em>top</em> = 0.9</dt>
<dd>the top of the subplots of the figure</dd>
<dt><em>wspace</em> = 0.2</dt>
<dd>the amount of width reserved for blank space between subplots</dd>
<dt><em>hspace</em> = 0.2</dt>
<dd>the amount of height reserved for white space between subplots</dd>
</dl>
<p>If you want additional control, you can create an
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><ttclass="xref py py-class docutils literal"><spanclass="pre">Axes</span></tt></a> using the
<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.add_axes" title="matplotlib.figure.Figure.add_axes"><ttclass="xref py py-meth docutils literal"><spanclass="pre">add_axes()</span></tt></a> method), which allows you to
<p>where all values are in fractional (0 to 1) coordinates. See
<aclass="reference internal" href="../examples/pylab_examples/axes_demo.html#pylab-examples-axes-demo"><em>pylab_examples example code: axes_demo.py</em></a> for an example of placing axes manually.</p>
<spanid="howto-auto-adjust"></span><h3>Automatically make room for tick labels<aclass="headerlink" href="#automatically-make-room-for-tick-labels" title="Permalink to this headline">¶</a></h3>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<p>This is now easier to handle than ever before.
Calling <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.tight_layout" title="matplotlib.pyplot.tight_layout"><ttclass="xref py py-func docutils literal"><spanclass="pre">tight_layout()</span></tt></a> can fix many common
layout issues. See the <aclass="reference internal" href="../users/tight_layout_guide.html#plotting-guide-tight-layout"><em>Tight Layout guide</em></a>.</p>
<pclass="last">The information below is kept here in case it is useful for other
purposes.</p>
</div>
<p>In most use cases, it is enough to simply change the subplots adjust
parameters as described in <aclass="reference internal" href="#howto-subplots-adjust"><em>Move the edge of an axes to make room for tick labels</em></a>. But in some
cases, you don’t know ahead of time what your tick labels will be, or
how large they will be (data and labels outside your control may be
being fed into your graphing application), and you may need to
automatically adjust your subplot parameters based on the size of the
tick labels. Any <aclass="reference internal" href="../api/artist_api.html#matplotlib.text.Text" title="matplotlib.text.Text"><ttclass="xref py py-class docutils literal"><spanclass="pre">Text</span></tt></a> instance can report
its extent in window coordinates (a negative x coordinate is outside
the window), but there is a rub.</p>
<p>The <aclass="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.RendererBase" title="matplotlib.backend_bases.RendererBase"><ttclass="xref py py-class docutils literal"><spanclass="pre">RendererBase</span></tt></a> instance, which is
used to calculate the text size, is not known until the figure is
drawn (<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure.draw" title="matplotlib.figure.Figure.draw"><ttclass="xref py py-meth docutils literal"><spanclass="pre">draw()</span></tt></a>). After the window is
drawn and the text instance knows its renderer, you can call
<aclass="reference internal" href="../api/artist_api.html#matplotlib.text.Text.get_window_extent" title="matplotlib.text.Text.get_window_extent"><ttclass="xref py py-meth docutils literal"><spanclass="pre">get_window_extent()</span></tt></a>. One way to solve
this chicken and egg problem is to wait until the figure is draw by
connecting
(<aclass="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.FigureCanvasBase.mpl_connect" title="matplotlib.backend_bases.FigureCanvasBase.mpl_connect"><ttclass="xref py py-meth docutils literal"><spanclass="pre">mpl_connect()</span></tt></a>) to the
“on_draw” signal (<aclass="reference internal" href="../api/backend_bases_api.html#matplotlib.backend_bases.DrawEvent" title="matplotlib.backend_bases.DrawEvent"><ttclass="xref py py-class docutils literal"><spanclass="pre">DrawEvent</span></tt></a>) and
get the window extent there, and then do something with it, eg move
the left of the canvas over; see <aclass="reference internal" href="../users/event_handling.html#event-handling-tutorial"><em>Event handling and picking</em></a>.</p>
<p>Here is an example that gets a bounding box in relative figure coordinates
(0..1) of each of the labels and uses it to move the left of the subplots
over so that the tick labels fit in the figure</p>
<spanclass="n">fig</span><spanclass="o">.</span><spanclass="n">subplots_adjust</span><spanclass="p">(</span><spanclass="n">left</span><spanclass="o">=</span><spanclass="mf">1.1</span><spanclass="o">*</span><spanclass="n">bbox</span><spanclass="o">.</span><spanclass="n">width</span><spanclass="p">)</span><spanclass="c"># pad a little</span>
<spanid="howto-ticks"></span><h3>Configure the tick linewidths<aclass="headerlink" href="#configure-the-tick-linewidths" title="Permalink to this headline">¶</a></h3>
<p>In matplotlib, the ticks are <em>markers</em>. All
<aclass="reference internal" href="../api/artist_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><ttclass="xref py py-class docutils literal"><spanclass="pre">Line2D</span></tt></a> objects support a line (solid,
dashed, etc) and a marker (circle, square, tick). The tick linewidth
is controlled by the “markeredgewidth” property:</p>
<spanid="howto-align-label"></span><h3>Align my ylabels across multiple subplots<aclass="headerlink" href="#align-my-ylabels-across-multiple-subplots" title="Permalink to this headline">¶</a></h3>
<p>If you have multiple subplots over one another, and the y data have
different scales, you can often get ylabels that do not align
vertically across the multiple subplots, which can be unattractive.
By default, matplotlib positions the x location of the ylabel so that
it does not overlap any of the y ticks. You can override this default
behavior by specifying the coordinates of the label. The example
below shows the default behavior in the left subplots, and the manual
<spanclass="n">ax1</span><spanclass="o">.</span><spanclass="n">set_title</span><spanclass="p">(</span><spanclass="s">'ylabels not aligned'</span><spanclass="p">)</span>
<spanid="date-index-plots"></span><h3>Skip dates where there is no data<aclass="headerlink" href="#skip-dates-where-there-is-no-data" title="Permalink to this headline">¶</a></h3>
<p>When plotting time series, eg financial time series, one often wants
to leave out days on which there is no data, eg weekends. By passing
in dates on the x-xaxis, you get large horizontal gaps on periods when
there is not data. The solution is to pass in some proxy x-data, eg
evenly sampled indices, and then use a custom formatter to format
these as dates. The example below shows how to use an ‘index formatter’
<spanclass="n">r</span><spanclass="o">=</span><spanclass="n">r</span><spanclass="p">[</span><spanclass="o">-</span><spanclass="mi">30</span><spanclass="p">:]</span><spanclass="c"># get the last 30 days</span>
<spanid="point-in-poly"></span><h3>Test whether a point is inside a polygon<aclass="headerlink" href="#test-whether-a-point-is-inside-a-polygon" title="Permalink to this headline">¶</a></h3>
<p>The <ttclass="xref py py-mod docutils literal"><spanclass="pre">nxutils</span></tt> provides two high-performance methods:
for a single point use <ttclass="xref py py-func docutils literal"><spanclass="pre">pnpoly()</span></tt> and for an
array of points use <ttclass="xref py py-func docutils literal"><spanclass="pre">points_inside_poly()</span></tt>.
For a discussion of the implementation see <aclass="reference external" href="http://www.ecse.rpi.edu/Homepages/wrf/Research/Short_Notes/pnpoly.html">pnpoly</a>.</p>
For a complete example, see <aclass="reference internal" href="../examples/event_handling/lasso_demo.html#event-handling-lasso-demo"><em>event_handling example code: lasso_demo.py</em></a>.</div>
<spanid="howto-set-zorder"></span><h3>Control the depth of plot elements<aclass="headerlink" href="#control-the-depth-of-plot-elements" title="Permalink to this headline">¶</a></h3>
<p>Within an axes, the order that the various lines, markers, text,
See <aclass="reference internal" href="../examples/pylab_examples/zorder_demo.html#pylab-examples-zorder-demo"><em>pylab_examples example code: zorder_demo.py</em></a> for a complete example.<p>You can also use the Axes property
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.set_axisbelow" title="matplotlib.axes.Axes.set_axisbelow"><ttclass="xref py py-meth docutils literal"><spanclass="pre">set_axisbelow()</span></tt></a> to control whether the grid
lines are placed above or below your other plot elements.</p>
<spanid="howto-axis-equal"></span><h3>Make the aspect ratio for plots equal<aclass="headerlink" href="#make-the-aspect-ratio-for-plots-equal" title="Permalink to this headline">¶</a></h3>
See <aclass="reference internal" href="../examples/pylab_examples/equal_aspect_ratio.html#pylab-examples-equal-aspect-ratio"><em>pylab_examples example code: equal_aspect_ratio.py</em></a> for a complete example.</div>
<divclass="section" id="make-a-movie">
<spanid="howto-movie"></span><h3>Make a movie<aclass="headerlink" href="#make-a-movie" title="Permalink to this headline">¶</a></h3>
<p>If you want to take an animated plot and turn it into a movie, the
best approach is to save a series of image files (eg PNG) and use an
external tool to convert them to a movie. You can use <aclass="reference external" href="http://www.mplayerhq.hu/DOCS/HTML/en/mencoder.html">mencoder</a>,
which is part of the <aclass="reference external" href="http://www.mplayerhq.hu">mplayer</a> suite
for this:</p>
<divclass="highlight-python"><pre>#fps (frames per second) controls the play speed
<p>The swiss army knife of image tools, ImageMagick’s <aclass="reference external" href="http://www.imagemagick.org/script/convert.php">convert</a> works for this as
well.</p>
<p>Here is a simple example script that saves some PNGs, makes them into
a movie, and then cleans up:</p>
<divclass="highlight-python"><pre>import os, sys
import matplotlib.pyplot as plt
files = []
fig = plt.figure(figsize=(5,5))
ax = fig.add_subplot(111)
for i in range(50): # 50 frames
ax.cla()
ax.imshow(rand(5,5), interpolation='nearest')
fname = '_tmp%03d.png'%i
print 'Saving frame', fname
fig.savefig(fname)
files.append(fname)
print 'Making movie animation.mpg - this make take a while'
Josh Lifton provided this example <aclass="reference internal" href="../examples/old_animation/movie_demo.html#old-animation-movie-demo"><em>old_animation example code: movie_demo.py</em></a>, which
is possibly dated since it was written in 2004.</div>
<divclass="section" id="multiple-y-axis-scales">
<spanid="howto-twoscale"></span><h3>Multiple y-axis scales<aclass="headerlink" href="#multiple-y-axis-scales" title="Permalink to this headline">¶</a></h3>
<p>A frequent request is to have two scales for the left and right
y-axis, which is possible using <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.twinx" title="matplotlib.pyplot.twinx"><ttclass="xref py py-func docutils literal"><spanclass="pre">twinx()</span></tt></a> (more
than two scales are not currently supported, though it is on the wish
list). This works pretty well, though there are some quirks when you
are trying to interactively pan and zoom, because both scales do not get
<aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.twiny" title="matplotlib.pyplot.twiny"><ttclass="xref py py-func docutils literal"><spanclass="pre">twiny()</span></tt></a>) to use <em>2 different axes</em>,
turning the axes rectangular frame off on the 2nd axes to keep it from
obscuring the first, and manually setting the tick locs and labels as
desired. You can use separate matplotlib.ticker formatters and
locators as desired because the two axes are independent.</p>
See <aclass="reference internal" href="../examples/api/two_scales.html#api-two-scales"><em>api example code: two_scales.py</em></a> for a complete example</div>
<spanid="howto-batch"></span><h3>Generate images without having a window appear<aclass="headerlink" href="#generate-images-without-having-a-window-appear" title="Permalink to this headline">¶</a></h3>
<p>The easiest way to do this is use a non-interactive backend (see
<aclass="reference internal" href="usage_faq.html#what-is-a-backend"><em>What is a backend?</em></a>) such as Agg (for PNGs), PDF, SVG or PS. In
your figure-generating script, just call the
<aclass="reference internal" href="../api/matplotlib_configuration_api.html#matplotlib.use" title="matplotlib.use"><ttclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.use()</span></tt></a> directive before importing pylab or
<pclass="last"><aclass="reference internal" href="#howto-webapp"><em>Matplotlib in a web application server</em></a> for information about running matplotlib inside
of a web application.</p>
</div>
</div>
<divclass="section" id="use-show">
<spanid="howto-show"></span><h3>Use <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.show" title="matplotlib.pyplot.show"><ttclass="xref py py-func docutils literal"><spanclass="pre">show()</span></tt></a><aclass="headerlink" href="#use-show" title="Permalink to this headline">¶</a></h3>
<p>When you want to view your plots on your display,
the user interface backend will need to start the GUI mainloop.
This is what <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.show" title="matplotlib.pyplot.show"><ttclass="xref py py-func docutils literal"><spanclass="pre">show()</span></tt></a> does. It tells
matplotlib to raise all of the figure windows created so far and start
the mainloop. Because this mainloop is blocking by default (i.e., script
execution is paused), you should only call this once per script, at the end.
Script execution is resumed after the last window is closed. Therefore, if
you are using matplotlib to generate only images and do not want a user
interface window, you do not need to call <ttclass="docutils literal"><spanclass="pre">show</span></tt> (see <aclass="reference internal" href="#howto-batch"><em>Generate images without having a window appear</em></a>
and <aclass="reference internal" href="usage_faq.html#what-is-a-backend"><em>What is a backend?</em></a>).</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Because closing a figure window invokes the destruction of its plotting
elements, you should call <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.savefig" title="matplotlib.pyplot.savefig"><ttclass="xref py py-func docutils literal"><spanclass="pre">savefig()</span></tt></a><em>before</em>
calling <ttclass="docutils literal"><spanclass="pre">show</span></tt> if you wish to save the figure as well as view it.</p>
</div>
<divclass="versionadded">
<p><span>New in version v1.0.0: </span><ttclass="docutils literal"><spanclass="pre">show</span></tt> now starts the GUI mainloop only if it isn’t already running.
Therefore, multiple calls to <ttclass="docutils literal"><spanclass="pre">show</span></tt> are now allowed.</p>
</div>
<p>Having <ttclass="docutils literal"><spanclass="pre">show</span></tt> block further execution of the script or the python
interpreter depends on whether matplotlib is set for interactive mode
or not. In non-interactive mode (the default setting), execution is paused
until the last figure window is closed. In interactive mode, the execution
is not paused, which allows you to create additional figures (but the script
won’t finish until the last figure window is closed).</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Support for interactive/non-interactive mode depends upon the backend.
Until version 1.0.0 (and subsequent fixes for 1.0.1), the behavior of
the interactive mode was not consistent across backends.
As of v1.0.1, only the macosx backend differs from other backends
because it does not support non-interactive mode.</p>
</div>
<p>Because it is expensive to draw, you typically will not want matplotlib
to redraw a figure many times in a script such as the following:</p>
<divclass="highlight-python"><divclass="highlight"><pre><spanclass="n">plot</span><spanclass="p">([</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="mi">3</span><spanclass="p">])</span><spanclass="c"># draw here ?</span>
<spanclass="n">xlabel</span><spanclass="p">(</span><spanclass="s">'time'</span><spanclass="p">)</span><spanclass="c"># and here ?</span>
<spanclass="n">ylabel</span><spanclass="p">(</span><spanclass="s">'volts'</span><spanclass="p">)</span><spanclass="c"># and here ?</span>
<spanclass="n">title</span><spanclass="p">(</span><spanclass="s">'a simple plot'</span><spanclass="p">)</span><spanclass="c"># and here ?</span>
<p>However, it is <em>possible</em> to force matplotlib to draw after every command,
which might be what you want when working interactively at the
python console (see <aclass="reference internal" href="../users/shell.html#mpl-shell"><em>Using matplotlib in a python shell</em></a>), but in a script you want to
defer all drawing until the call to <ttclass="docutils literal"><spanclass="pre">show</span></tt>. This is especially
important for complex figures that take some time to draw.
<aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.show" title="matplotlib.pyplot.show"><ttclass="xref py py-func docutils literal"><spanclass="pre">show()</span></tt></a> is designed to tell matplotlib that
you’re all done issuing commands and you want to draw the figure now.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last"><aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.show" title="matplotlib.pyplot.show"><ttclass="xref py py-func docutils literal"><spanclass="pre">show()</span></tt></a> should typically only be called at
most once per script and it should be the last line of your
script. At that point, the GUI takes control of the interpreter.
<p>This is not what show does and unfortunately, because doing blocking
calls across user interfaces can be tricky, is currently unsupported,
though we have made significant progress towards supporting blocking events.</p>
<divclass="versionadded">
<p><span>New in version v1.0.0: </span>As noted earlier, this restriction has been relaxed to allow multiple
calls to <ttclass="docutils literal"><spanclass="pre">show</span></tt>. In <em>most</em> backends, you can now expect to be
able to create new figures and raise them in a subsequent call to
<ttclass="docutils literal"><spanclass="pre">show</span></tt> after closing the figures from a previous call to <ttclass="docutils literal"><spanclass="pre">show</span></tt>.</p>
</div>
</div>
</div>
<divclass="section" id="contributing-howto">
<spanid="howto-contribute"></span><h2>Contributing: howto<aclass="headerlink" href="#contributing-howto" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="submit-a-patch">
<spanid="how-to-submit-patch"></span><h3>Submit a patch<aclass="headerlink" href="#submit-a-patch" title="Permalink to this headline">¶</a></h3>
<p>See <aclass="reference internal" href="../devel/gitwash/patching.html#making-patches"><em>Making patches</em></a> for information on how to make a patch with git.</p>
<p>If you are posting a patch to fix a code bug, please explain your
patch in words – what was broken before and how you fixed it. Also,
even if your patch is particularly simple, just a few lines or a
single function replacement, we encourage people to submit git diffs
against HEAD of the branch they are patching. It just makes life
easier for us, since we (fortunately) get a lot of contributions, and
want to receive them in a standard format. If possible, for any
non-trivial change, please include a complete, free-standing example
that the developers can run unmodified which shows the undesired
behavior pre-patch and the desired behavior post-patch, with a clear
verbal description of what to look for. A developer may
have written the function you are working on years ago, and may no
longer be with the project, so it is quite possible you are the world
expert on the code you are patching and we want to hear as much detail
as you can offer.</p>
<p>When emailing your patch and examples, feel free to paste any code
into the text of the message, indeed we encourage it, but also attach
the patches and examples since many email clients screw up the
formatting of plain text, and we spend lots of needless time trying to
reformat the code to make it usable.</p>
<p>You should check out the guide to developing matplotlib to make sure
<spanid="how-to-contribute-docs"></span><h3>Contribute to matplotlib documentation<aclass="headerlink" href="#contribute-to-matplotlib-documentation" title="Permalink to this headline">¶</a></h3>
<p>matplotlib is a big library, which is used in many ways, and the
documentation has only scratched the surface of everything it can
do. So far, the place most people have learned all these features are
through studying the examples (<aclass="reference internal" href="#how-to-search-examples"><em>Search examples</em></a>), which is a
recommended and great way to learn, but it would be nice to have more
official narrative documentation guiding people through all the dark
corners. This is where you come in.</p>
<p>There is a good chance you know more about matplotlib usage in some
areas, the stuff you do every day, than many of the core developers
who wrote most of the documentation. Just pulled your hair out
compiling matplotlib for windows? Write a FAQ or a section for the
<aclass="reference internal" href="installing_faq.html#installing-faq"><em>Installation</em></a> page. Are you a digital signal processing wizard?
Write a tutorial on the signal analysis plotting functions like
<aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.specgram" title="matplotlib.pyplot.specgram"><ttclass="xref py py-func docutils literal"><spanclass="pre">specgram()</span></tt></a>. Do you use matplotlib with
<aclass="reference external" href="http://www.djangoproject.com/">django</a> or other popular web
application servers? Write a FAQ or tutorial and we’ll find a place
for it in the <aclass="reference internal" href="../users/index.html#users-guide-index"><em>User’s Guide</em></a>. Bundle matplotlib in a
<aclass="reference external" href="http://www.py2exe.org/">py2exe</a> app? ... I think you get the idea.</p>
<p>matplotlib is documented using the <aclass="reference external" href="http://sphinx.pocoo.org/index.html">sphinx</a> extensions to restructured text
<aclass="reference external" href="http://docutils.sourceforge.net/rst.html">(ReST)</a>. sphinx is an
extensible python framework for documentation projects which generates
HTML and PDF, and is pretty easy to write; you can see the source for this
document or any page on this site by clicking on the <em>Show Source</em> link
at the end of the page in the sidebar (or <aclass="reference external" href="../_sources/faq/howto_faq.txt">here</a> for this document).</p>
<p>The sphinx website is a good resource for learning sphinx, but we have
put together a cheat-sheet at <aclass="reference internal" href="../devel/documenting_mpl.html#documenting-matplotlib"><em>Documenting matplotlib</em></a> which
shows you how to get started, and outlines the matplotlib conventions
and extensions, eg for including plots directly from external code in
your documents.</p>
<p>Once your documentation contributions are working (and hopefully
tested by actually <em>building</em> the docs) you can submit them as a patch
against git. See <aclass="reference internal" href="../devel/gitwash/git_install.html#install-git"><em>Install git</em></a> and <aclass="reference internal" href="#how-to-submit-patch"><em>Submit a patch</em></a>.
Looking for something to do? Search for <aclass="reference external" href="../search.html?q=todo">TODO</a>.</p>
<spanid="howto-webapp"></span><h2>Matplotlib in a web application server<aclass="headerlink" href="#matplotlib-in-a-web-application-server" title="Permalink to this headline">¶</a></h2>
<p>Many users report initial problems trying to use maptlotlib in web
application servers, because by default matplotlib ships configured to
work with a graphical user interface which may require an X11
connection. Since many barebones application servers do not have X11
enabled, you may get errors if you don’t configure matplotlib for use
in these environments. Most importantly, you need to decide what
kinds of images you want to generate (PNG, PDF, SVG) and configure the
appropriate default backend. For 99% of users, this will be the Agg
backend, which uses the C++ <aclass="reference external" href="http://antigrain.com">antigrain</a>
rendering engine to make nice PNGs. The Agg backend is also
configured to recognize requests to generate other output formats
(PDF, PS, EPS, SVG). The easiest way to configure matplotlib to use
Agg is to call:</p>
<divclass="highlight-python"><divclass="highlight"><pre><spanclass="c"># do this before importing pylab or pyplot</span>
<spanclass="n">imgdata</span><spanclass="o">.</span><spanclass="n">seek</span><spanclass="p">(</span><spanclass="mi">0</span><spanclass="p">)</span><spanclass="c"># rewind the data</span>
<spanid="howto-click-maps"></span><h3>Clickable images for HTML<aclass="headerlink" href="#clickable-images-for-html" title="Permalink to this headline">¶</a></h3>
<p>Andrew Dalke of <aclass="reference external" href="http://www.dalkescientific.com">Dalke Scientific</a>
has written a nice <aclass="reference external" href="http://www.dalkescientific.com/writings/diary/archive/2005/04/24/interactive_html.html">article</a>
on how to make html click maps with matplotlib agg PNGs. We would
also like to add this functionality to SVG and add a SWF backend to
support these kind of images. If you are interested in contributing
to these efforts that would be great.</p>
</div>
</div>
<divclass="section" id="search-examples">
<spanid="how-to-search-examples"></span><h2>Search examples<aclass="headerlink" href="#search-examples" title="Permalink to this headline">¶</a></h2>
<p>The nearly 300 code <aclass="reference internal" href="../examples/index.html#examples-index"><em>Matplotlib Examples</em></a> included with the matplotlib
source distribution are full-text searchable from the <aclass="reference internal" href="../search.html"><em>Search Page</em></a>
page, but sometimes when you search, you get a lot of results from the
<aclass="reference internal" href="../api/index.html#api-index"><em>The Matplotlib API</em></a> or other documentation that you may not be interested
in if you just want to find a complete, free-standing, working piece
of example code. To facilitate example searches, we have tagged every
code example page with the keyword <ttclass="docutils literal"><spanclass="pre">codex</span></tt> for <em>code example</em> which
shouldn’t appear anywhere else on this site except in the FAQ.
So if you want to search for an example that uses an
ellipse, <aclass="reference internal" href="../search.html"><em>Search Page</em></a> for <ttclass="docutils literal"><spanclass="pre">codex</span><spanclass="pre">ellipse</span></tt>.</p>
</div>
<divclass="section" id="cite-matplotlib">
<spanid="how-to-cite-mpl"></span><h2>Cite Matplotlib<aclass="headerlink" href="#cite-matplotlib" title="Permalink to this headline">¶</a></h2>
<p>If you want to refer to matplotlib in a publication, you can use
“Matplotlib: A 2D Graphics Environment” by J. D. Hunter In Computing
in Science & Engineering, Vol. 9, No. 3. (2007), pp. 90-95 (see <aclass="reference external" href="https://doi.org/10.1109/MCSE.2007.55">this