Hints on getting from here (an idea) to there (a publishable plot)¶

• Start with Screenshots for the broad plotting capabilities
• Go to the thumbnail gallery and scan the thumbnails to find something similar.
• Googling is unfortunately not the best way to get to the detailed help for particular functions. For example googling “matplotlib errorbar” just gives the home page and the pyplot API docs. The errorbar() function is then not so easy to find.
• Instead use Search and enter the function name. Most of the high-level plotting functions are in the pyplot module and you can find them quickly by searching for pyplot.<function>, e.g. pyplot.errorbar.
• When you are ready to put your plot into a paper for publication see the page on Publication-quality plots.

Basic plots¶

So let’s get started with plotting using a standard startup idiom that will work for both interactive and scripted plotting. In this case we are working interactively so fire up ipython in the usual way with the standard imports for numpy and matplotlib:

$ ipython --matplotlib

import numpy as np
import matplotlib.pyplot as plt

matplotlib.pyplot is a collection of command style functions that make matplotlib work like MATLAB. Each pyplot function makes some change to a figure: eg, create a figure, create a plotting area in a figure, plot some lines in a plotting area, decorate the plot with labels, etc. Plotting with matplotlib.pyplot is stateful, in that it keeps track of the current figure and plotting area, and the plotting functions are directed to the current axes:

plt.figure()          # Make a new figure window
plt.plot([1,2,3,4])
plt.ylabel('some numbers')

You may be wondering why the x-axis ranges from 0-2 and the y-axis from 1-3. If you provide a single list or array to the plot() command, matplotlib assumes it is a sequence of y values, and automatically generates the x values for you. Since python ranges start with 0, the default x vector has the same length as y but starts with 0. Hence the x data are [0,1,2].

plot() is a versatile command, and will take an arbitrary number of arguments. For example, to plot x versus y, you can issue the command:

plt.clf()
plt.plot([1,2,3,4], [1,4,9,16])

Plot() is just the tip of the iceberg for plotting commands and you should study the page of matplotlib screenshots to get a better picture.

For every x, y pair of arguments, there is an optional third argument which is the format string that indicates the color and line type of the plot. The letters and symbols of the format string are from MATLAB, and you concatenate a color string with a line style string. The default format string is ‘b-‘, which is a solid blue line. For example, to plot the above with red circles, you would issue:

plt.clf()
plt.plot([1,2,3,4], [1,4,9,16], 'ro')
plt.axis([0, 6, 0, 20])

See the plot() documentation for a complete list of line styles and format strings. The axis() command in the example above takes a list of [xmin, xmax, ymin, ymax] and specifies the viewport of the axes.

If matplotlib were limited to working with lists, it would be fairly useless for numeric processing. Generally, you will use NumPy arrays. In fact, all sequences are converted to numpy arrays internally. The example below illustrates a plotting several lines with different format styles in one command using arrays:

# evenly sampled time at 200ms intervals
t = np.arange(0., 5., 0.2)

# red dashes, blue squares and green triangles
# then filled circle with connecting line
plt.clf()
plt.plot(t, t, 'r--', t, t**2, 'bs', t, t**3, 'g^')
plt.plot(t, t+60, 'o', linestyle='-', color='c')

Exercise: Make this plot

Use the plot() documentation to make a plot that looks similar to the one above. Start with:

x = [1, 2, 3, 4]
y = [3, 2, 3, 1]

Click to Show/Hide Solution

x = [1, 2, 3, 4]
y = [3, 2, 3, 1]
plt.clf()
plt.plot(x, y, '-.', linewidth=10)
plt.plot(x, y, 'H', markeredgecolor='b', markeredgewidth=10, markerfacecolor='r', markersize=40)
plt.axis([0, 5, 0, 4])

What are all these icons for?¶

The figures are enclosed in a window that looks a little like the following (it depends on the OS and matplotlib backend being used):

The icons at the bottom of the window allow you to zoom in or out of the plot, pan around, and save the plot as a “hardcopy” format (e.g. PNG, postscript, or PDF). The first icon will reset you to the original axis limits, which comes in quite handy.

You can use the close button to close the window, but it is best to use the close() command to avoid memory leaks.

Saving the plot¶

As discussed above, you can use the GUI to save the plot, but the savefig() command is often more useful, and has many options:

plt.savefig('fig.png')
plt.savefig('fig.pdf')

Note that you can save a figure multiple times (e.g. as different formats). The supported formats depend on the backend being used, but normally include png, pdf, ps, eps and svg:

plt.savefig('fig')   # creates fig.png (unless you have changed the default format)
plt.savefig('fig.pdf')  # creates a PDF file, fig.pdf
plt.savefig('fig', format='svg')  # creates a SVG file called fig
plt.savefig('fig.svg', 'format='ps') # creates a PS file called fig.svg (do not do this!)

The default format (used in the first line) can be queried, or changed, by saying:

>>> rcParams['savefig.format']
'png'
>>> rcParams['savefig.format'] = 'pdf'
>>> plt.savefig('foo')  # creates foo.pdf

Some common-ish Python errors¶

Here’s a couple of errors you may come across:

>>> plt.clf
<function matplotlib.pyplot.clf>
>>> x = np.arange(5)
>>> x.size()
TypeError: 'int' object is not callable

Since clf is a function then you need to add () to actually call it (being able to refer to a function as a “thing” is incredibly powerful, which is what has happened here, but it’s not much use if you just want to clear the current figure).

For the second case, x.size returns an integer (in this case 5), which we then call as a function, leading to the somewhat cryptic messsage above. For new users it would be nice if it said “hold on, size isn’t callable”, but then this would inhibit useful - if complex - statements such as:

tarfile.open(fileobj=request.urlopen(url), mode='r|').extractall()

Controlling line properties¶

Lines have many attributes that you can set: linewidth, dash style, antialiased, etc; see Line2D. There are several ways to set line properties

• Use keyword args:

  x = np.arange(0, 10, 0.25)
  y = np.sin(x)
  plt.clf()
  plt.plot(x, y, linewidth=4.0)
  

• Use the setp() command. The example below uses a MATLAB-style command to set multiple properties on a list of lines. setp works transparently with a list of objects or a single object:

  plt.clf()
  lines = plt.plot(x, y, 'r', x/2, y/2, 'b')
  plt.setp(lines, color='r', linewidth=4.0)
  

• Use the setter methods of the Line2D instance. plot returns a list of lines; eg line1, line2 = plot(x1,y1,x2,x2). Below I have only one line so it is a list of length 1. I use tuple unpacking in the line, = plot(x, y, 'o') to get the first element of the list:

  plt.clf()
  line, = plt.plot(x, y, '-')
  line.set_<TAB>
  

  Now change the line color, noting that in this case you need to explicitly redraw:

  line.set_color('m') # change color
  plt.draw()
  

Here are the available Line2D properties.

To get a list of settable line properties, call the setp() function with a line or lines as argument:

lines = plt.plot([1,2,3])
plt.setp(lines)

Figure, Axes, plot(), and subplot()

Figure

This is the entire window where one or more subplots live. A Figure object (new window) is created with the figure() command.

Axes

This is an object representing a subplot (which you might casually call a “plot”) which contains axes, ticks, lines, points, text, etc.

plot()

This is a command that draws points or lines and returns a list of Line2D objects. One sublety is that plot() will automatically call figure() and/or subplot() if neccesary to create the underlying Figure and Axes objects.

subplot()

This is a command that creates and returns a new subplot (Axes) object which will be used for subsequent plotting commands.

Using close

You can use the ‘close button’ provided by the window manager to remove the figure, but if you do this you must still call the close() command, to ensure that memory allocated by pyplot for the figure is released. This is only really an issue for long-running ipython sessions; if you just create a single plot and then exit you do not need to use close.

Exercise: Overlaying histograms

Make an additional normal distribution with a mean of 130. Make a new plot where the two distributions are overlayed. Use a different color and choose the opacities so it looks reasonable.

Hint:

• You might want to use the bin parameter with an arange(min, max, step) so both histograms are binned the same.

Getting the fonts just right¶

The global font properties for various plot elements can be controlled using the rc() function:

plt.rc("font", size=10, family='normal', weight='bold')
plt.rc("axes", labelsize=10, titlesize=10)
plt.rc("xtick", labelsize=10)
plt.rc("ytick", labelsize=10)
plt.rc("legend", fontsize=10)

The inconsistency here is one of the warts in matplotlib. Ironically my favorite way to find these valuable commands is to google “matplotlib makes me hate” which brings up a blog post ranting about the problems with matplotlib.

All of the attributes that can be controlled with the rc() command are listed in $HOME/.matplotlib/matplotlibrc and Customizing matplotlib.

See also the Advanced plotting page.