Matplotlib is a Python 2-d and 3-d plotting library which produces publication quality figures in a variety of formats and interactive environments across platforms. Matplotlib can be used in Python scripts, the Python and IPython shell, web application servers, and six graphical user interface toolkits.
The matplotlib documentation is extensive and covers all the functionality in detail. The documentation is littered with hundreds of examples showing a plot and the exact source code making the plot:
- Matplotlib home page: key plotting commands in a table
- Pyplot tutorial: intro to 1-D plotting
- Interactive navigation: how to use the plot window for zooming etc.
- Screenshots: screenshots and code for about 20 key types of matplotlib functionality
- Thumbnail gallery: hundreds of thumbnails (find a plot like the one you want to make)
- Text intro: manipulate text
- Mathematical expressions: put math in figure text or labels
- FAQ: FAQ, including a useful Howto section (e.g. multiple y-axis scales, make plot aspect ratio equal, etc)
- Search: find documentation for specific functions or general concepts
- Customizing matplotlib: making it beautiful and well-behaved
- Line2D: knobs to twiddle for customizing a line or points in a plot
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
pyplotmodule and you can find them quickly by searching for
- When you are ready to put your plot into a paper for publication see the page on Publication-quality plots.
Plotting 1-d data¶
The matplotlib tutorial on Pyplot (Copyright (c) 2002-2009 John D. Hunter; All Rights Reserved and license) is an excellent introduction to basic 1-d plotting. The content below has been adapted from the pyplot tutorial source with some changes and the addition of exercises.
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
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
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])
Clearing the figure with plt.clf()
From now on we will assume that you know to clear the figure with clf() before entering commands to make the next plot.
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
[xmin, xmax, ymin, ymax] and specifies the viewport of the
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:
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
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:
Controlling line properties¶
What are lines and markers?
A matplotlib “line” is a object containing a set of points and various attributes describing how to draw those points. The points are optionally drawn with “markers” and the connections between points can be drawn with various styles of line (including no connecting line at all).
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.
setpworks 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
plotreturns 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()
In contrast to old-school plotting where you issue a plot command and the line is immortalized, in matplotlib the lines (and basically everything about the plot) are dynamic objects that can be modified after the fact.
Here are the available Line2D properties.
|animated||[True | False]|
|antialiased or aa||[True | False]|
|clip_box||a matplotlib.transform.Bbox instance|
|clip_on||[True | False]|
|clip_path||a Path instance and a Transform instance, a Patch|
|color or c||any matplotlib color|
|contains||the hit testing function|
|dash_capstyle||[‘butt’ | ‘round’ | ‘projecting’]|
|dash_joinstyle||[‘miter’ | ‘round’ | ‘bevel’]|
|dashes||sequence of on/off ink in points|
|data||(array xdata, array ydata)|
|figure||a matplotlib.figure.Figure instance|
|linestyle or ls||[ ‘-‘ | ‘–’ | ‘-.’ | ‘:’ | ‘steps’ | ...]|
|linewidth or lw||float value in points|
|lod||[True | False]|
|marker||[ ‘+’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ... ]|
|markeredgecolor or mec||any matplotlib color|
|markeredgewidth or mew||float value in points|
|markerfacecolor or mfc||any matplotlib color|
|markersize or ms||float|
|markevery||None | integer | (startind, stride)|
|picker||used in interactive line selection|
|pickradius||the line pick selection radius|
|solid_capstyle||[‘butt’ | ‘round’ | ‘projecting’]|
|solid_joinstyle||[‘miter’ | ‘round’ | ‘bevel’]|
|transform||a matplotlib.transforms.Transform instance|
|visible||[True | False]|
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)
Detour into Python
You may have noticed that in the last workshop we mostly used NumPy arrays like
np.array([1,2,3,4]) but now you are seeing statements like
Some useful functions for controlling plotting¶
Here are a few useful functions:
|figure()||Make new figure frame (accepts figsize=(width,height) in inches)|
|autoscale()||Allow or disable autoscaling and control space beyond data limits|
|hold()||Hold figure: hold(False) means next plot() command wipes figure|
|ion(), ioff()||Turn interactive plotting on and off|
|axis()||Set plot axis limits or set aspect ratio (plus more)|
|subplots_adjust()||Adjust the spacing around subplots (fix clipped labels etc)|
|xlim(), ylim()||Set x and y axis limits individually|
|xticks(), yticks()||Set x and y axis ticks|
Working with multiple figures and axes¶
MATLAB, and matplotlib.pyplot, have the concept of the current figure and the current axes. All plotting commands apply to the current axes. The function gca() returns the current axes (an Axes instance), and gcf() returns the current figure (a Figure instance). Normally, you don’t have to worry about this, because it is all taken care of behind the scenes.
Figure, Axes, plot(), and subplot()
- This is the entire window where one or more subplots live. A Figure object (new window) is created with the figure() command.
- This is an object representing a subplot (which you might casually call a “plot”) which contains axes, ticks, lines, points, text, etc.
- 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.
- This is a command that creates and returns a new subplot (Axes) object which will be used for subsequent plotting commands.
Below is a script that illustrates this by creating two figures where the first figure has two subplots:
def f(t): """Python function to calculate a decaying sinusoid""" val = np.exp(-t) * np.cos(2*np.pi*t) return val t1 = np.arange(0.0, 5.0, 0.1) t2 = np.arange(0.0, 5.0, 0.02) plt.figure(1) # Make the first figure plt.clf() plt.subplot(2, 1, 1) # 2 rows, 1 column, plot 1 plt.plot(t1, f(t1), 'bo', t2, f(t2), 'k') plt.title('FIGURE 1') plt.text(2, 0.8, 'AXES 211') plt.subplot(2, 1, 2) # 2 rows, 1 column, plot 2 plt.plot(t2, np.cos(2*np.pi*t2), 'r--') plt.text(2, 0.8, 'AXES 212') plt.figure(2) # Make a second figure plt.clf() plt.plot(t2, f(t2), '*') plt.grid() plt.title('FIGURE 2') plt.text(2, 0.8, 'AXES 111')
The first figure() command here is optional because
figure(1) will be created by default, just as a
subplot(1, 1, 1)
will be created by default if you don’t manually specify an axes.
The subplot() command specifies
numrows, numcols, fignum where
fignum ranges from 1 to
numrows*numcols. The commas in the
command are optional if
numrows*numcols<10 so you might see calls like
subplot(211) in code, but don’t do this yourself. You can create an
arbitrary number of subplots and axes.
If you want to place an axes manually, ie, not on a rectangular grid, use the
axes() command, which allows you to specify the location as
bottom, width, height]) where all values are in fractional (0 to 1)
coordinates. See pylab_examples-axes_demo
for an example of placing axes manually and pylab_examples-line_styles
for an example with lots-o-subplots.
You can move back to existing subplots, or indeed figures, as shown below:
plt.figure(1) # Select the existing first figure plt.subplot(2, 1, 2) # Select the existing subplot 212 plt.plot(t2, np.cos(np.pi*t2), 'g--') # Add a plot to the axes plt.text(0.2, -0.8, 'Back to AXES 212', color='g', size=18) # add a colored label, increasing the font size
You can clear the current figure with clf() and the current axes with cla(). If you find this statefulness, annoying, don’t despair, this is just a thin stateful wrapper around an object oriented API, which you can use instead. See the Advanced plotting page for an introduction to this approach, and the then Artist tutorial for the gory details.
Figures can be deleted with the close() command:
plt.close(2) # Remove the second figure
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
ipython sessions; if you just create a single
plot and then exit you do not need to use
Working with text¶
The text() command can be used to add text in an arbitrary location, and the xlabel(), ylabel() and title() are used to add text in the indicated locations (see Text intro for a more detailed example):
mu, sigma = 100, 15 x = np.random.normal(mu, sigma, size=10000) plt.clf() # the histogram of the data histvals, binvals, patches = plt.hist(x, bins=50, normed=True, facecolor='g', alpha=0.75) plt.xlabel('Smarts') plt.ylabel('Probability') plt.title('Histogram of IQ') plt.text(60, .025, r'$\mu=100,\ \sigma=15$') plt.axis([40, 160, 0, 0.03]) plt.grid(True)
All of the text() commands return an
matplotlib.text.Text instance. Just as with with lines
above, you can customize the properties by passing keyword arguments
into the text functions or using setp():
t = plt.xlabel('my data', fontsize=14, color='red')
These properties are covered in more detail in text-properties.
Click to Show/Hide Solution
plt.clf() x2 = np.random.normal(130, sigma, size=10000) out = plt.hist(x, bins=50, facecolor='g', alpha=0.5) out2 = plt.hist(x2, bins=50, facecolor='r', alpha=0.5)
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.
See also the Advanced plotting page.
Using mathematical expressions in text¶
matplotlib accepts TeX equation expressions in any text expression. For example to write the expression in the title, you can write a TeX expression surrounded by dollar signs:
r preceeding the title string is important – it signifies that the
string is a raw string and not to treate backslashes as python escapes.
matplotlib has a built-in TeX expression parser and layout engine, and ships
its own math fonts – for details see the mathtext-tutorial. Thus you can use
mathematical text across platforms without requiring a TeX installation. For
those who have LaTeX and dvipng installed, you can also use LaTeX to format
your text and incorporate the output directly into your display figures or
saved postscript – see the usetex-tutorial.
The uses of the basic text() command above
place text at an arbitrary position on the Axes. A common use case of
text is to annotate some feature of the plot, and the
annotate() method provides helper
functionality to make annotations easy. In an annotation, there are
two points to consider: the location being annotated represented by
xy and the location of the text
xytext. Both of
these arguments are
plt.clf() t = np.arange(0.0, 5.0, 0.01) s = np.cos(2*pi*t) lines = plt.plot(t, s, lw=2) plt.annotate('local max', xy=(2, 1), xytext=(3, 1.5), arrowprops=dict(facecolor='black', shrink=0.05)) plt.ylim(-2,2)
In this basic example, both the
xy (arrow tip) and
locations (text location) are in data coordinates. There are a
variety of other coordinate systems one can choose – see the
for more details and links to examples.
Plotting 2-d data¶
A deeper tutorial on plotting 2-d image data will have to wait for another day:
Plotting 3-d data¶
Matplotlib supports plotting 3-d data through the
module. This is a somewhat specialized functionality but it’s worth quickly
looking at an example of the 3-d viewer that is available:
from mpl_toolkits.mplot3d import Axes3D def randrange(n, vmin, vmax): return (vmax-vmin)*np.random.rand(n) + vmin fig = plt.figure() ax = fig.add_subplot(111, projection='3d') n = 100 for c, m, zl, zh in [('r', 'o', -50, -25), ('b', '^', -30, -5)]: xs = randrange(n, 23, 32) ys = randrange(n, 0, 100) zs = randrange(n, zl, zh) ax.scatter(xs, ys, zs, c=c, marker=m) ax.set_xlabel('X Label') ax.set_ylabel('Y Label') ax.set_zlabel('Z Label')
To get more information check out the mplot3d tutorial.
Appendix: Pylab and Pyplot and NumPy¶
You may see examples that use the
pylab mode of IPython by using
ipython --pylab or the
%pylab magic function.
Let’s demystify what’s happening in this case and
clarify the relationship between pylab and pyplot.
matplotlib.pyplot is a collection of command style functions that make matplotlib work like MATLAB. This is just a package module that you can import:
import matplotlib.pyplot print(sorted(dir(matplotlib.pyplot)))
Likewise pylab is also a module provided by matplotlib that you can import:
This module is a thin wrapper around
matplotlib.pylab which pulls in:
- Everything in
- All top-level functions
- A selection of other useful functions and modules from matplotlib
There is no magic, and to see for yourself do
import matplotlib.pylab matplotlib.pylab?? # prints the source code!!
When you do
ipython --pylab it (essentially) just does:
from pylab import *
There is one technical detail about GUI event loops and plot window interaction
which makes it useful to use
--pylab even if you are not directly using all the
top-level functions like
plot() that get imported.
In a lot of documentation examples you will see code like:
import matplotlib.pyplot as plt # set plt as alias for matplotlib.pyplot plt.plot([1,2], [3,4])
Now you should understand this is the same
plot() function that you get in
See Matplotlib, pylab, and pyplot: how are they related? for a more discussion on the topic.