# This line configures matplotlib to show figures embedded in the notebook, # instead of opening a new window for each figure. More about that later. # If you are using an old version of IPython, try using '%pylab inline' instead.%pylabinline
Populating the interactive namespace from numpy and matplotlib
Matplotlib is an excellent 2D and 3D graphics library for generating scientific figures. Some of the many advantages of this library include:
Easy to get started
Great control of every element in a figure, including figure size and DPI.
High-quality output in many formats, including PNG, PDF, SVG, EPS, and PGF.
GUI for interactively exploring figures and support for headless generation of figure files (useful for batch jobs).
One of the key features of matplotlib that I would like to emphasize, and that I think makes matplotlib highly suitable for generating figures for scientific publications is that all aspects of the figure can be controlled programmatically. This is important for reproducibility and convenient when one needs to regenerate the figure with updated data or change its appearance.
The good thing about the pylab MATLAB-style API is that it is easy to get started with if you are familiar with MATLAB, and it has a minumum of coding overhead for simple plots.
However, I'd encourrage not using the MATLAB compatible API for anything but the simplest figures.
Instead, I recommend learning and using matplotlib's object-oriented plotting API. It is remarkably powerful. For advanced figures with subplots, insets and other components it is very nice to work with.
The matplotlib object-oriented API
The main idea with object-oriented programming is to have objects that one can apply functions and actions on, and no object or program states should be global (such as the MATLAB-like API). The real advantage of this approach becomes apparent when more than one figure is created, or when a figure contains more than one subplot.
To use the object-oriented API we start out very much like in the previous example, but instead of creating a new global figure instance we store a reference to the newly created figure instance in the fig variable, and from it we create a new axis instance axes using the add_axes method in the Figure class instance fig:
fig=plt.figure()axes=fig.add_axes([0.2,0.2,0.8,0.8])# left, bottom, width, height (range 0 to 1)axes.plot(x,y,'r')axes.set_xlabel('x')axes.set_ylabel('y')axes.set_title('title');
Although a little bit more code is involved, the advantage is that we now have full control of where the plot axes are placed, and we can easily add more than one axis to the figure:
fig=plt.figure()axes1=fig.add_axes([0.1,0.1,0.8,0.8])# main axesaxes2=fig.add_axes([0.2,0.5,0.4,0.3])# inset axes# main figureaxes1.plot(x,y,'r')axes1.set_xlabel('x')axes1.set_ylabel('y')axes1.set_title('title')# insertaxes2.plot(y,x,'g')axes2.set_xlabel('y')axes2.set_ylabel('x')axes2.set_title('insert title');
If we don't care about being explicit about where our plot axes are placed in the figure canvas, then we can use one of the many axis layout managers in matplotlib. My favorite is subplots, which can be used like this:
Matplotlib allows the aspect ratio, DPI and figure size to be specified when the Figure object is created, using the figsize and dpi keyword arguments. figsize is a tuple of the width and height of the figure in inches, and dpi is the dots-per-inch (pixel per inch). To create an 800x400 pixel, 100 dots-per-inch figure, we can do:
<matplotlib.figure.Figure at 0x7f52d0daf6a0>
The same arguments can also be passed to layout managers, such as the subplots function:
To save a figure to a file we can use the savefig method in the Figure class:
Here we can also optionally specify the DPI and choose between different output formats:
What formats are available and which ones should be used for best quality?
Matplotlib can generate high-quality output in a number formats, including PNG, JPG, EPS, SVG, PGF and PDF. For scientific papers, I recommend using PDF whenever possible. (LaTeX documents compiled with pdflatex can include PDFs using the includegraphics command). In some cases, PGF can also be good alternative.
Legends, labels and titles
Now that we have covered the basics of how to create a figure canvas and add axes instances to the canvas, let's look at how decorate a figure with titles, axis labels, and legends.
A title can be added to each axis instance in a figure. To set the title, use the set_title method in the axes instance:
Similarly, with the methods set_xlabel and set_ylabel, we can set the labels of the X and Y axes:
In [ ]:
Legends for curves in a figure can be added in two ways. One method is to use the legend method of the axis object and pass a list/tuple of legend texts for the previously defined curves:
The method described above follows the MATLAB API. It is somewhat prone to errors and unflexible if curves are added to or removed from the figure (resulting in a wrongly labelled curve).
A better method is to use the label="label text" keyword argument when plots or other objects are added to the figure, and then using the legend method without arguments to add the legend to the figure:
The advantage with this method is that if curves are added or removed from the figure, the legend is automatically updated accordingly.
The legend function takes an optional keyword argument loc that can be used to specify where in the figure the legend is to be drawn. The allowed values of loc are numerical codes for the various places the legend can be drawn. See http://matplotlib.org/users/legend_guide.html#legend-location for details. Some of the most common loc values are:
ax.legend(loc=0)# let matplotlib decide the optimal locationax.legend(loc=1)# upper right cornerax.legend(loc=2)# upper left cornerax.legend(loc=3)# lower left cornerax.legend(loc=4)# lower right corner# .. many more options are available
<matplotlib.legend.Legend at 0x7f52d0178080>
The following figure shows how to use the figure title, axis labels and legends described above:
fig,ax=plt.subplots()ax.plot(x,x**2,label="y = x**2")ax.plot(x,x**3,label="y = x**3")ax.legend(loc=2);# upper left cornerax.set_xlabel('x (cm)')ax.set_ylabel('y (Watts)')ax.set_title('title');
Setting colors, linewidths, linetypes
With matplotlib, we can define the colors of lines and other graphical elements in a number of ways. First of all, we can use the MATLAB-like syntax where 'b' means blue, 'g' means green, etc. The MATLAB API for selecting line styles are also supported: where, for example, 'b.-' means a blue line with dots:
# MATLAB style line color and style ax.plot(x,x**2,'b.-')# blue line with dotsax.plot(x,x**3,'g--')# green dashed line
We can also define colors by their names or RGB hex codes and optionally provide an alpha value using the color and alpha keyword arguments:
fig,ax=plt.subplots()ax.plot(x,x+1,color="red",alpha=0.5)# half-transparant redax.plot(x,x+2,color="#07B541")# RGB hex code for a bluish colorax.plot(x,x+3,color="#15cc55")# RGB hex code for a greenish color
[<matplotlib.lines.Line2D at 0x7f52dc175cc0>]
Line and marker styles
To change the line width, we can use the linewidth or lw keyword argument. The line style can be selected using the linestyle or ls keyword arguments:
fig,ax=plt.subplots(figsize=(12,6))ax.plot(x,x+1,color="blue",linewidth=0.25)ax.plot(x,x+2,color="blue",linewidth=0.50)ax.plot(x,x+3,color="blue",linewidth=1.00)ax.plot(x,x+4,color="blue",linewidth=2.00)# possible linestype options ‘-‘, ‘--’, ‘-.’, ‘:’, ‘steps’ax.plot(x,x+5,color="red",lw=2,linestyle='-')ax.plot(x,x+6,color="red",lw=2,ls='-.')ax.plot(x,x+7,color="red",lw=2,ls=':')# custom dashline,=ax.plot(x,x+8,color="black",lw=1.50)line.set_dashes([5,10,15,10])# format: line length, space length, ...# possible marker symbols: marker = '+', 'o', '*', 's', ',', '.', '1', '2', '3', '4', ...ax.plot(x,x+9,color="green",lw=2,ls='--',marker='+')ax.plot(x,x+10,color="green",lw=2,ls='--',marker='o')ax.plot(x,x+11,color="green",lw=2,ls='--',marker='s')ax.plot(x,x+12,color="green",lw=2,ls='--',marker='1')# marker size and colorax.plot(x,x+13,color="purple",lw=1,ls='-',marker='o',markersize=2)ax.plot(x,x+14,color="purple",lw=1,ls='-',marker='o',markersize=4)ax.plot(x,x+15,color="purple",lw=1,ls='-',marker='o',markersize=8,markerfacecolor="red")ax.plot(x,x+16,color="purple",lw=1,ls='-',marker='s',markersize=8,markerfacecolor="yellow",markeredgewidth=2,markeredgecolor="blue");
Control over axis appearance
The appearance of the axes is an important aspect of a figure that we often need to modify to make a publication quality graphics. We need to be able to control where the ticks and labels are placed, modify the font size and possibly the labels used on the axes. In this section we will look at controling those properties in a matplotlib figure.
The first thing we might want to configure is the ranges of the axes. We can do this using the set_ylim and set_xlim methods in the axis object, or axis('tight') for automatrically getting "tightly fitted" axes ranges:
It is also possible to set a logarithmic scale for one or both axes. This functionality is in fact only one application of a more general transformation system in Matplotlib. Each of the axes' scales are set seperately using set_xscale and set_yscale methods which accept one parameter (with the value "log" in this case):
In addition to the regular plot method, there are a number of other functions for generating different kind of plots. See the matplotlib plot gallery for a complete list of available plot types: http://matplotlib.org/gallery.html. Some of the more useful ones are show below:
Axes can be added to a matplotlib Figure canvas manually using fig.add_axes or using a sub-figure layout manager such as subplots, subplot2grid, or gridspec:
In [ ]:
Colormap and contour figures
Colormaps and contour figures are useful for plotting functions of two variables. In most of these functions we will use a colormap to encode one dimension of the data. There are a number of predefined colormaps. It is relatively straightforward to define custom colormaps. For a list of pre-defined colormaps, see: http://www.scipy.org/Cookbook/Matplotlib/Show_colormaps
To use 3D graphics in matplotlib, we first need to create an instance of the Axes3D class. 3D axes can be added to a matplotlib figure canvas in exactly the same way as 2D axes; or, more conveniently, by passing a projection='3d' keyword argument to the add_axes or add_subplot methods.
fig=plt.figure(figsize=(14,6))# `ax` is a 3D-aware axis instance because of the projection='3d' keyword argument to add_subplotax=fig.add_subplot(1,2,1,projection='3d')p=ax.plot_surface(X,Y,Z,rstride=4,cstride=4,linewidth=0)# surface_plot with color grading and color barax=fig.add_subplot(1,2,2,projection='3d')p=ax.plot_surface(X,Y,Z,rstride=1,cstride=1,cmap=matplotlib.cm.coolwarm,linewidth=0,antialiased=False)cb=fig.colorbar(p,shrink=0.5)