PC204 – The matplotlib Plotting Package

Matplotlib is a comprehensive Python plotting library for producing publication-quality figures. It has excellent documentation, example code for each type of plot, and lots of options so that you can make your plots look just the way you want. Take a look at the matplotlib image gallery to see the wealth of different plots this package is capable of making.

Matplotlib requires numpy, a package for handling large numerical arrays and performing operations such as linear algebra, random number generation, and Fourier transforms. The current release of matplotlib, version 1.3.1, requires numpy version 1.5 or later, and numpy itself requires Python version 2.6 or later.

Installation Instructions

Typically, you install matplotlib by downloading an installer from Source Forge. On Microsoft Windows and Linux, you need to make sure that you have Numeric Python already installed, and that you select the appropriate version of the installer (e.g., 32- vs. 64-bit, Python version, etc). Then you just run the installer and the result will be a working matplotlib module.

On OS X 10.9 (Mavericks), both numpy and matplotlib come pre-installed by Apple, so you do not need to do anything. On earlier OS X releases, the easiest way to install these packages is to install Enthought Canopy Express, which is an "open and intuitive environment for technical and scientific computing." Canopy Express consists of Python and over 30 packages, including matplotlib and numpy, and installs in the /Application directory. The main thing to remember is that the Canopy Express version of Python differs from the system Python shipped by Apple. (Canopy Express is the free version of the package. There is also Canopy which includes even more packages and may be used freely with an academic license.)

On Windows, Canopy Express is installed in C:\Python27, which is the same location as the installer from python.org. (If you already have Python 2.7 installed, you will probably want to uninstall it before installing Canopy Express.) python.exe and pythonw.exe in the install folder are the Python executables. When run, python.exe will display a console window (generally what you want) while pythonw.exe will not (useful when running a program with a graphical user interface).

Old Installation Notes:

Instructions in this section are for historical reference purposes only. For new installations of matplotlib, please follow the Installation Instructions above.

OS X 10.7 (Lion) and OS X 10.8 (Mountain Lion):
As of October 20, 2011, the Source Forge installer for matplotlib does not work with all releases of Mac OS X and, in particular, not with 10.7 (Lion). The problems arise from incompatible binaries and system libraries. Therefore, as an alternative to installing just matplotlib, you can install a complete Python distribution from Enthought. This approach also works for earlier versions of OS X, and because it includes many other useful Python packages is now the preferred solution for all versions of OS X prior to 10.9, and can be used for Windows and Linux too.

The Enthought Python Distribution (EPD) includes not only Python, but also over 90 libraries including matplotlib. Students or employees from degree-granting institutions may use these [Enthought Python Distributions] for an extended period free of cost. The EPD download page has an button at the bottom; if you click this button and enter your UCSF e-mail address, you will receive a mail message with the link for downloading an EPD installer. The installer is over 200MB in size and expands to over 1GB when installed.

On the Mac, EPD is installed in /Applications/Enthought, which contains apps and examples, and in /Library/Frameworks/EPD64.framework. The main hurdle with using Enthought Python on Mac OS X is that their Tkinter uses the X11 window system rather than the native Apple window system. For example, on Mac OS X 10.8 (Mountain Lion) which by default does not have X11 installed, attempts to use Tkinter, e.g., using the swampy package, will bring up a dialog saying that X11 is no longer distributed with Mac OS X and that X11 must be obtained from http://xquartz.macosforge.org. The X11 download is named XQuartz-2.7.4.dmg (or perhaps a newer version) which contains XQuartz.pkg; doubleclicking on the .dmg file will open it in Finder, and doubleclicking on the .pkg file will install X11. (You may need to restart your computer to guarantee that the proper background processes are running.) Once X11 is installed, doubleclicking on IDLE (64-bit) in /Applications/Enthought will start up Python's Integrated DeveLopment Environment. Even without X11 installed, you can doubleclick on QtConsole (64-bit) to start up an IPython intepreter using the native Mac OS X window system. (The IPython interpreter handles a superset of the Python language, so you can treat it the same as a regular Python interpreter. If you use Qt rather than Tkinter as your graphical interface toolkit, you should not need to install X11.) The EPD installer also updates your shell setup so that typing python in a Terminal window will invoke EPD Python rather than the system Python.

OS X 10.6 (Snow Leopard):
Snow Leopard comes with Python 2.6.1 and numpy 1.2.1, so these versions are just fine. All you have to do is download this matplotlib package built especially for OS X 10.6 and install it. To install the package, save the file and double click it, which will run the Installer. When the "Select a Destination" panel in the Installer appears, click on "Install for all users of this computer" and click Continue. You will also need to enter the administrator password for your computer.

OS X 10.5 (Leopard):
Leopard includes Python version 2.5.1, but it unfortunately includes an older replease of numpy (1.0.1) that is not compatible with matplotlib. To make matters worse, Leopard keeps Python together with other Mac "system" files and this makes it difficult to just download and install a newer release of numpy. (If you try to install numpy 1.2.1 on OS X 10.5 you'll get the rather obscure error message "numpy requires python.org Framework Build Python 2.5 to install.") The easiest approach is just to go the python.org web site, download and install Python 2.6.2, then download and install numpy 1.3.0, and finally download and install matplotlib 0.99.1.1. The only disadvantage of this approach is that you'll use up a little more disk space by having two copies of Python installed on your computer, but most systems have plenty of space available and so this is not really a problem.

Windows:
Microsoft Windows doesn't come with any version of Python pre-installed and the easiest approach is just to install Canopy Express as described above.

Testing

Regardless of what operating system you're using, try running this simple Python script to verify that matplotlib is working properly:

from matplotlib import pyplot
from pylab import randn
x = randn(1000)
y = pyplot.hist(x, bins=100)
pyplot.show()

This creates a simple histogram of 1,000 zero-mean, unit-variance Gaussian random numbers generated by the randn() function.

Troubleshooting

If you run into problems installing matplotlib or one of the other packages mentioned above, the easier thing to do is come see one of the course instructors for help.

Alternative Packages

If for some reason matplotlib isn't the right package for you, you might consider one of these alternatives:

• gnuplot.py – a Python wrapper to the popular gnuplot plotting package
• pmw.blt – a Python interface to the BLT Toolkit extension to Tcl/Tk, with basic support for producing 2D graphs, barcharts, and stripcharts