Find all objects in figure of a certain type

Every matplotlib artist (see :ref:`artist-tutorial`) has a method called :meth:`~matplotlib.artist.Artist.findobj` that can be used to recursively search the artist for any artists it may contain that meet some criteria (eg match all :class:`~matplotlib.lines.Line2D` instances or match some arbitrary filter function). For example, the following snippet finds every object in the figure which has a set_color property and makes the object blue:

def myfunc(x):
    return hasattr(x, 'set_color')

for o in fig.findobj(myfunc):
    o.set_color('blue')

You can also filter on class instances:

import matplotlib.text as text
for o in fig.findobj(text.Text):
    o.set_fontstyle('italic')

Save transparent figures

The :meth:`~matplotlib.pyplot.savefig` command has a keyword argument transparent which, if True, will make the figure and axes backgrounds transparent when saving, but will not affect the displayed image on the screen. If you need finer grained control, eg you do not want full transparency or you to affect the screen displayed version as well, you can set the alpha properties directly. The figure has a :class:`matplotlib.patches.Rectangle` instance called patch and the axes has a Rectangle instance called patch. You can set any property on them directly (facecolor, edgecolor, linewidth, linestyle, alpha). Eg:

fig = plt.figure()
fig.patch.set_alpha(0.5)
ax = fig.add_subplot(111)
ax.patch.set_alpha(0.5)

If you need all the figure elements to be transparent, there is currently no global alpha setting, but you can set the alpha channel on individual elements, eg:

ax.plot(x, y, alpha=0.5)
ax.set_xlabel('volts', alpha=0.5)

Move the edge of an axes to make room for tick labels

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 :meth:`matplotlib.figure.Figure.subplots_adjust` method (in pyplot it is :func:`~matplotlib.pyplot.subplots_adjust`). For example, to move the bottom of the subplots up to make room for some rotated x tick labels:

fig = plt.figure()
fig.subplots_adjust(bottom=0.2)
ax = fig.add_subplot(111)

You can control the defaults for these parameters in your :file:`matplotlibrc` file; see :ref:`customizing-matplotlib`. For example, to make the above setting permanent, you would set:

figure.subplot.bottom : 0.2   # the bottom of the subplots of the figure

The other parameters you can configure are, with their defaults

left = 0.125

the left side of the subplots of the figure

right = 0.9

the right side of the subplots of the figure

bottom = 0.1

the bottom of the subplots of the figure

top = 0.9

the top of the subplots of the figure

wspace = 0.2

the amount of width reserved for blank space between subplots

hspace = 0.2

the amount of height reserved for white space between subplots

If you want additional control, you can create an :class:`~matplotlib.axes.Axes` using the :func:`~matplotlib.pyplot.axes` command (or equivalently the figure :meth:`matplotlib.figure.Figure.add_axes` method), which allows you to specify the location explicitly:

ax = fig.add_axes([left, bottom, width, height])

where all values are in fractional (0 to 1) coordinates. See axes_demo.py for an example of placing axes manually.

Automatically make room for tick labels

In most use cases, it is enough to simpy change the subplots adjust parameters as described in :ref:`howto-subplots-adjust`. 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 :class:`matplotlib.text.Text` instance can report its extent in window coordinates (a negative x coordinate is outside the window), but there is a rub.

The :class:`matplotlib.backend_bases.RendererBase` instance, which is used to calculate the text size, is not known until the figure is drawn (:meth:`matplotlib.figure.Figure.draw`). After the window is drawn and the text instance knows its renderer, you can call :meth:`matplotlib.text.Text.get_window_extent`. One way to solve this chicken and egg problem is to wait until the figure is draw by connecting (:meth:`matplotlib.backend_bases.FigureCanvasBase.mpl_connect`) to the "on_draw" signal (:class:`~matplotlib.backend_bases.DrawEvent`) and get the window extent there, and then do something with it, eg move the left of the canvas over; see :ref:`event-handling-tutorial`.

Here is 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

Configure the tick linewidths

In matplotlib, the ticks are markers. All :class:`~matplotlib.lines.Line2D` objects support a line (solid, dashed, etc) and a marker (circle, square, tick). The tick linewidth is controlled by the "markeredgewidth" property:

import matplotlib.pyplot as plt
fig = plt.figure()
ax = fig.add_subplot(111)
ax.plot(range(10))

for line in ax.get_xticklines() + ax.get_yticklines():
    line.set_markersize(10)

plt.show()

The other properties that control the tick marker, and all markers, are markerfacecolor, markeredgecolor, markeredgewidth, markersize. For more information on configuring ticks, see :ref:`axis-container` and :ref:`tick-container`.

Align my ylabels across multiple subplots

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 setting in the right subplots.

Skip dates where there is no data

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 indicies, and then use a custom formatter to format these as dates. The example below shows how to use an 'index formatter' to achieve the desired plot:

import numpy as np
import matplotlib.pyplot as plt
import matplotlib.mlab as mlab
import matplotlib.ticker as ticker

r = mlab.csv2rec('../data/aapl.csv')
r.sort()
r = r[-30:]  # get the last 30 days

N = len(r)
ind = np.arange(N)  # the evenly spaced plot indices

def format_date(x, pos=None):
    thisind = np.clip(int(x+0.5), 0, N-1)
    return r.date[thisind].strftime('%Y-%m-%d')

fig = plt.figure()
ax = fig.add_subplot(111)
ax.plot(ind, r.adj_close, 'o-')
ax.xaxis.set_major_formatter(ticker.FuncFormatter(format_date))
fig.autofmt_xdate()

plt.show()

Test whether a point is inside a polygon

The :mod:`matplotlib.nxutils` provides two high performance methods: for a single point use :func:`~matplotlib.nxutils.pnpoly` and for an array of points use :func:`~matplotlib.nxutils.points_inside_poly`. For a discussion of the implementation see pnpoly.

In [25]: import numpy as np

In [26]: import matplotlib.nxutils as nx

In [27]: verts = np.array([ [0,0], [0, 1], [1, 1], [1,0]], float)

In [28]: nx.pnpoly( 0.5, 0.5, verts)
Out[28]: 1

In [29]: nx.pnpoly( 0.5, 1.5, verts)
Out[29]: 0

In [30]: points = np.random.rand(10,2)*2

In [31]: points
Out[31]:
array([[ 1.03597426,  0.61029911],
       [ 1.94061056,  0.65233947],
       [ 1.08593748,  1.16010789],
       [ 0.9255139 ,  1.79098751],
       [ 1.54564936,  1.15604046],
       [ 1.71514397,  1.26147554],
       [ 1.19133536,  0.56787764],
       [ 0.40939549,  0.35190339],
       [ 1.8944715 ,  0.61785408],
       [ 0.03128518,  0.48144145]])

In [32]: nx.points_inside_poly(points, verts)
Out[32]: array([False, False, False, False, False, False, False,  True, False, True], dtype=bool)

Control the depth of plot elements

Within an axes, the order that the various lines, markers, text, collections, etc appear is determined by the :meth:`matplotlib.artist.Artist.set_zorder` property. The default order is patches, lines, text, with collections of lines and collections of patches appearing at the same level as regular lines and patches, respectively:

line, = ax.plot(x, y, zorder=10)

You can also use the Axes property :meth:`matplotlib.axes.Axes.set_axisbelow` to control whether the grid lines are placed above or below your other plot elements.

Make the aspect ratio for plots equal

The Axes property :meth:`matplotlib.axes.Axes.set_aspect` controls the aspect ratio of the axes. You can set it to be 'auto', 'equal', or some ratio which controls the ratio:

ax = fig.add_subplot(111, aspect='equal')

Make a movie

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 mencoder, which is part of the mplayer suite for this:

#fps (frames per second) controls the play speed
mencoder 'mf://*.png' -mf type=png:fps=10 -ovc \\
   lavc -lavcopts vcodec=wmv2 -oac copy -o animation.avi

The swiss army knife of image tools, ImageMagick's convert works for this as well.

Here is a simple example script that saves some PNGs, makes them into a movie, and then cleans up:

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'
os.system("mencoder 'mf://_tmp*.png' -mf type=png:fps=10 \\
  -ovc lavc -lavcopts vcodec=wmv2 -oac copy -o animation.mpg")

Multiple y-axis scales

A frequent request is to have two scales for the left and right y-axis, which is possible using :func:`~matplotlib.pyplot.twinx` (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, since both scales do not get the signals.

The approach :func:`~matplotlib.pyplot.twinx` (and its sister :func:`~matplotlib.pyplot.twiny`) uses is to use 2 different axes, 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 since the two axes are independent:

import numpy as np
import matplotlib.pyplot as plt

fig = plt.figure()
ax1 = fig.add_subplot(111)
t = np.arange(0.01, 10.0, 0.01)
s1 = np.exp(t)
ax1.plot(t, s1, 'b-')
ax1.set_xlabel('time (s)')
ax1.set_ylabel('exp')

ax2 = ax1.twinx()
s2 = np.sin(2*np.pi*t)
ax2.plot(t, s2, 'r.')
ax2.set_ylabel('sin')
plt.show()

Generate images without having a window popup

The easiest way to do this is use an image backend (see :ref:`what-is-a-backend`) such as Agg (for PNGs), PDF, SVG or PS. In your figure generating script, just place call :func:`matplotlib.use` directive before importing pylab or pyplot:

import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
plt.plot([1,2,3])
plt.savefig('myfig')

Use :func:`~matplotlib.pyplot.show`

The user interface backends need to start the GUI mainloop, and this is what :func:`~matplotlib.pyplot.show` does. It tells matplotlib to raise all of the figure windows and start the mainloop. Because the mainloop is blocking, you should only call this once per script, at the end. If you are using matplotlib to generate images only and do not want a user interface window, you do not need to call show (see :ref:`howto-batch` and :ref:`what-is-a-backend`).

Because it is expensive to draw, matplotlib does not want to redrawing the figure many times in a script such as the following:

plot([1,2,3])            # draw here ?
xlabel('time')           # and here ?
ylabel('volts')          # and here ?
title('a simple plot')   # and here ?
show()

It is possible to force matplotlib to draw after every command, which is what you usually want when working interactively at the python console (see :ref:`mpl-shell`), but in a script you want to defer all drawing until the script has executed. This is especially important for complex figures that take some time to draw. :func:`~matplotlib.pyplot.show` is designed to tell matplotlib that you're all done issuing commands and you want to draw the figure now.

Many users are frustrated by show because they want it to be a blocking call that raises the figure, pauses the script until the figure is closed, and then allows the script to continue running until the next figure is created and the next show is made. Something like this:

# WARNING : illustrating how NOT to use show
for i in range(10):
    # make figure i
    show()

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 some progress towards supporting blocking events.

Submit a patch

First obtain a copy of matplotlib svn (see :ref:`install-svn`) and make your changes to the matplotlib source code or documentation and apply a svn diff. If it is feasible, do your diff from the top level directory, the one that contains :file:`setup.py`. Eg,:

> cd /path/to/matplotlib/source
> svn diff > mypatch.diff

and then post your patch to the matplotlib-devel mailing list. If you do not get a response within 24 hours, post your patch to the sourceforge patch tracker, and follow up on the mailing list with a link to the sourceforge patch submissions. If you still do not hear anything within a week (this shouldn't happen!), send us a kind and gentle reminder on the mailing list.

If you have made lots of local changes and do not want to a diff against the entire tree, but rather against a single directory or file, that is fine, but we do prefer svn diffs against HEAD.

You should check out the guide to developing matplotlib to make sure your patch abides by our coding conventions :ref:`developers-guide-index`.

Contribute to matplotlib documentation

matplotlib is a big library, which is used in many ways, and the documentation we have only scratches the surface of everything it can do. So far, the place most people have learned all these features are through studying the examples (:ref:`how-to-search-examples`), 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.

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 write most of the documentation. Just pulled your hair out compiling matplotlib for windows? Write a FAQ or a section for the :ref:`installing` page. Are you a digital signal processing wizard? Write a tutorial on the signal analysis plotting functions like :func:`~matplotlib.pyplot.xcorr`, :func:`~matplotlib.pyplot.psd` and :func:`~matplotlib.pyplot.specgram`. Do you use matplotlib with django or other popular web application servers? Write a FAQ or tutorial and we'll find a place for it in the :ref:`users-guide-index`. Bundle matplotlib in a py2exe app? ... I think you get the idea.

matplotlib is documented using the sphinx extensions to restructured text ReST. sphinx is a 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 Show Source link at the end of the page in the sidebar (or here for this document).

The sphinx website is a good resource for learning sphinx, but we have put together a cheat-sheet at :ref:`documenting-matplotlib` 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.

Once your documentation contributions are working (and hopefully tested by actually building the docs) you can submit them as a patch against svn. See :ref:`install-svn` and :ref:`how-to-submit-patch`. Looking for something to do? Search for TODO.

matplotlib with apache

TODO; see :ref:`how-to-contribute-docs`.

matplotlib with django

TODO; see :ref:`how-to-contribute-docs`.

matplotlib with zope

TODO; see :ref:`how-to-contribute-docs`.

Clickable images for HTML

Andrew Dalke of Dalke Scientific has written a nice article 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.