\documentclass[]{book}
\usepackage{graphicx}
\usepackage{color}
\usepackage{graphics}
\usepackage{listings}
\usepackage{natbib}
\usepackage{fullpage}
\usepackage{amssymb}
\usepackage{verbatimfiles}
\usepackage{hyperref}
\title{The Matplotlib User's Guide}
\author{John Hunter}
\begin{document}
\lstset{
language=Python,
basicstyle=\small,
commentstyle=\color{blue},
stringstyle=\ttfamily,
showstringspaces=false,
% frame=single,
emph = {axes, axis, bar, cla, clf, clim, close, cohere, colorbar,
colors, csd, draw, errorbar, figimage, figlegend, figtext, figure,
fill, gca, gcf, gci, get, get_current_fig_manager,
get_plot_commands, gray, grid, hist, hlines, hold, imshow, jet,
legend, load, loglog, pcolor, pcolor_classic, plot, plot_date,
plotting, psd, raise_msg_to_str, rc, rcdefaults, save, savefig,
scatter, scatter_classic, semilogx, semilogy, set, specgram, stem,
subplot, table, text, title, vlines, xlabel, ylabel},
emphstyle = \color{black}, % color for matplotlib funcs
breaklines=true,
breakatwhitespace = true,
postbreak = \space\dots
}
\newcommand{\fig}[4]
{\begin{figure}[ht]
\begin{center}
\includegraphics[width=#1]{#2}
\caption{\label{#4} #3}
\end{center}
\end{figure}}
\newcommand{\matlab}[0]{matlab{\texttrademark}}
\newcommand{\fname}[1]{{\tt #1}}
\newcommand{\func}[1]{{\tt #1}}
\newcommand{\code}[1]{{\tt #1}}
\newcommand{\prompt}[1]{\code{>>> #1}}
\newcommand{\carg}[1]{\textit{#1}} % command argument
\newcommand{\val}[1]{\textit{#1}}
\newcommand{\rc}[1]{{\tt #1}}
% a pointer to matplotlib documentation
\newcommand{\mpldoc}[1]{#1}
%\newcommand{\url}[1]{{\tt #1}}
\maketitle
\chapter{Introduction}
\label{cha:introduction}
matplotlib is a library for making 2D plots of arrays in python.
Although it has its origins in emulating the \matlab\ graphics
commands, it does not require matlab, and can be used in a pythonic,
object oriented way. Although matplotlib is written primarily in pure
python, it makes heavy use of Numeric/numarray and other extension
code to provide good performance even for large arrays.
matplotlib is designed with the philosophy that you should be able to
create simple plots with just a few commands, or just one! If you
want to see a histogram of your data, you shouldn't need to
instantiate objects, call methods, set properties, and so it; it
should just work.
For years, I used to use matlab exclusively for data analysis and
visualization. matlab excels at making nice looking plots easy. When
I began working with EEG data, I found that I needed to write
applications to interact with my data, and developed and EEG analysis
application in matlab. As the application grew in complexity,
interacting with databases, http servers, manipulating complex data
structures, I began to strain against the limitations of matlab as a
programming language, and decided to start over in python. python
more than makes up for all of matlab's deficiencies as a programming
language, but I was having difficulty finding a 2D plotting package
(for 3D VTK more than exceeds all of my needs).
When I went searching for a python plotting package, I had several
requirements:
\begin{itemize}
\item Plots should look great - publication quality. One important
requirement for me is that the text looks good (antialiased, etc)
\item Postscript output for inclusion with \TeX\ documents
\item Embeddable in a graphical user interface for application
development
\item Code should be easy enough that I can understand it and extend
it.
\item Making plots should be easy.
\end{itemize}
\noindent Finding no package that suited me just right, I did what any
self-respecting python programmer would do: rolled up my sleeves and
dived in. Not having any real experience with computer graphics, I
decided to emulate matlab's plotting capabilities because that is
something matlab does very well. This had the added advantage that
many people have a lot of matlab experience, and thus they can quickly
get up to steam plotting in python. From a developer's perspective,
having a fixed user interface (the matplotlib.matlab interface) has
been very useful, because the guts of the code base can be redesigned
without affecting user code.
The matplotlib code is conceptually divided into three parts: the
\textit{matlab interface} is the set of functions provided by
matplotlib.matlab which allow the user to create plots with code quite
similar to matlab figure generating code. The \textit{matplotlib
frontend} or \textit{matplotlib API} is the set of classes that do
the heavy lifting, creating and managing figures, text, lines, plots
and so on. This is an abstract interface that knowns nothing about
output. The \textit{backends} are device dependent drawing devices,
aka renderers, that transform the frontend representation to hardcopy
or a display device. Example backends: PS creates postscript
hardcopy, SVG creates scalar vector graphics hardcopy, Agg creates PNG
output using the high quality antigrain library that ships with
matplotlib - \url{http://antigrain.com}, GTK embeds matplotlib in a
GTK application, GTKAgg uses the antigrain renderer to create a figure
and embed it a GTK application, and so on for WX, Tkinter, FLTK\dots.
matplotlib is used by many people in many different contexts. Some
people want to automatically generate postscript files to send to a
printer or publishers. Others deploy matplotlib on a web application
server to generate PNG output for inclusion in dynamically generated
web pages. Some use matplotlib interactively from the python shell in
Tkinter on windows. My primary use is to embed matplotlib in a GTK
EEG application that runs on windows, linux and OS X.
Because there are so many ways people want to use a plotting library,
there is a certain amount of complexity inherent in configuring the
library so that it will work naturally the way you want it to. To
manage this, a number of choices must be made when compiling and
running matplotlib: do you want to use it in a graphical user
interface (GUI) or just to generate hardcopy; which array package will
you use?
Most of this chapter will explain these options and how to configure
them. Before diving into these details, let's take a detour comparing
a typical matplotlib script with it's analog in matlab.
\section{Migrating from matlab}
\label{sec:migrating}
Using matplotlib should come naturally if you have ever plotted with
matlab, and should be fairly straightforward if you haven't. Like all
interpreted languages used for serious number crunching, python has an
extension module for processing numeric arrays. Numerical python has
been around since the early days, and already comes with many matlab
compatible analysis functions, which matplotlib extends. The example
code below shows two complete scripts: on the left hand side is python
with matplotlib, and on the right is matlab.
\fig{4in}{figures/psd_matlab}{Colored noise signal and power spectrum
generated with matlab as shown in Listing~\ref{lst:versus_matlab}.
Compare with matplotlib in Figure~\ref{fig:psd_py}.}{fig:psd_matlab}
Both scripts do the same thing: generate a white noise vector,
convolve it with an exponential function, add it to a sine wave, plot
the signal in one subplot and plot the power spectrum in another.
\begin{lstlisting}[caption={matplotlib and matlab}, label=lst:versus_matlab]
# python % matlab
from matplotlib.matlab import * % no import necessary
dt = 0.01 dt = 0.01;
t = arange(0,10,dt) t = [0:dt:10];
nse = randn(len(t)) nse = randn(size(t));
r = exp(-t/0.05) r = exp(-t/0.05);
cnse = conv(nse, r)*dt cnse = conv(nse, r)*dt;
cnse = cnse[:len(t)] cnse = cnse(1:length(t));
s = 0.1*sin(2*pi*t) + cnse s = 0.1*sin(2*pi*t) + cnse;
subplot(211) subplot(211)
plot(t,s) plot(t,s)
subplot(212) subplot(212)
psd(s, 512, 1/dt) psd(s, 512, 1/dt)
\end{lstlisting}
The major differences are 1) Numeric has a functions for creating
arrays (\func{arange} above) whereas matlab has the handy notation
\code{[0:dt:10]}, 2) python uses square brackets rather than
parentheses for array indexing, and there are some small differences
in how do array lengths, sizes, and indexing. But the differences are
minute compared to the similarities: 1) matlab and Numeric both do
array processing and have a variety of functions that efficiently
operate on arrays and scalars, 2) moderately sophisticated signal
processing (white noise, convolution, power spectra) is achieved in
only a few lines of clear code and 3) plots are simple, intuitive and
attractive (compare Figures~\ref{fig:psd_py} and
Figures~\ref{fig:psd_matlab}).
\fig{4in}{figures/psd_py}{Colored noise signal and power spectrum
generated with python matplotlib as shown in
Listing~\ref{lst:versus_matlab}. Compare with matlab in
Figure~\ref{fig:psd_matlab}. Note that the waveforms are not
identical because they were generated from random
signals!}{fig:psd_py}
\section{Numerix}
\label{sec:numerix}
Numeric is a python module for efficiently processing arrays of
numeric data. While highly optimized for performance and very stable,
some limitations in the design made it inefficient for very large
arrays, and developers decided it was better to start with a new array
package to solve some of these design problems and numarray was born.
matplotlib requires one of Numeric or numarray to operate. If you
have no experience with either, you are strongly advised to install
one of the packages and read through some of the documentation before
continuing, as this manual assumes you are familiar with one of them;
see \url{http://www.pfdubois.com/numpy/} and
\url{http://www.stsci.edu/resources/software_hardware/numarray}.
Currently the python computing community is in a state of transition
from Numeric to numarray, but this is happening slowly, in part
because numarray is slower than Numeric for smallish arrays, and in
part because a large code base is written around Numeric (notably
scipy). This latter concern should become less problematic with the
numarray/Numeric compatibility layer. For the near term, however,
there will be users who want to use one package or the other.
Fortunately, several numarray/Numeric developers are codevelopers of
matplotlib, giving matplotlib full Numeric and numarray compatibility,
thanks in large part to Todd Miller's matplotlib.numerix module and
the numarray compatibility layer for extension code. This allows you
to choose between Numeric or numarray at the prompt or in a config
file. Thus when you do
\begin{lstlisting}
# import matplotlib and all the numerix functions
from matplotlib.matlab import *
\end{lstlisting}
\noindent you'll not only get all the matplotlib matlab interface
commands, but most of the Numeric or numarray package as well
(depending on your numerix setting). All of the array creation and
manipulation functions are imported, such as \func{array},
\func{arange}, \func{take}, \func{where}, etc, as well as the
functions and classes outside the main module, such as \func{mean},
\func{randn}, \func{fft} and much more. To may your matplotlib
scripts as portable as possible with respect to your choice of array
packages, it is advised not to explicitly import Numeric or numarray.
Rather, you should use matplotlib.numerix where possible, either by
using the functions imported by \mpldoc{matplotlib.matlab}, or by
explicitly importing the numerix module, as in
\begin{lstlisting}
# create a numerix namespace
import matplotlib.numerix as n
x = n.arange(100)
y = n.take(x, range(10,20))
\end{lstlisting}
For the remainder of this manual, the term \textit{numerix} is used to
mean either the Numeric or numarray package.
\subsection{Choosing Numeric or numarray}
To select numarray or Numeric from the prompt, run your matplotlib
script with
\begin{verbatim}
> python myscript.py --numarray # use numarray
> python myscript.py --Numeric # use Numeric
\end{verbatim}
\noindent Typically, however, users will choose one or the other and
make this setting in their rc file using either \rc{numerix : Numeric}
or \rc{numerix : numarray}; see Section~\ref{sec:matplotlibrc}.
Some of the matplotlib extension code operates on Numeric or numarray
arrays, eg the image and transforms modules. To get optimum
performance, you should compile matplotlib with the proper flag for
the library you will be using most. Set the \code{NUMERIX} variable
in \fname{setup.py} before building. Note that this is different from
the \rc{numerix} variable in \fname{.matplotlibrc}. The former
affects the matplotlib at compile time, the latter at run time. All
of your matplotlib scripts should run without error regardless of
these two settings, but to get optimum performance, they should agree.
numarray builds for win32 are available on the download page.
\textit{If your NUMERIX compile time setting and numerix rc file
setting do not agree, your performance can suffer 10-fold. Before
compiling matplotlib, edit \fname{setup.py} and
\fname{.matplotlibrc} to make sure these settings agree. If you are
using a precompiled version of matplotlib, eg a windows installer,
make sure you choose the installer that agrees with the array
package you use most. The installer labelled 'numarray' is for
numarray users, whereas the unlabelled installer is for Numeric users.}
\section{Backends}
\label{sec:backends}
The matplotlib backends are responsible for taking the figure
representation and transferring this to a display device, either a
hardcopy image (\fname{*.jpg}, \fname{*.png}, \fname{*.ps},
\fname{*.svg}, etc) or a GUI window that you can interact with. There
are many GUIs for python: pygtk, wxpython, Tkinter, PyQT, pyfltk, and
more, and matplotlib supports most of them.
In choosing your backend, the following considerations are important
\begin{itemize}
\item What kind of output do you require? Any matplotlib installation
can generate PS and SVG. For other hardcopy formats, different
backends have different capabilities. Agg can only generate png but
produces the highest quality output (antialiased, alpha). The
native GTK and WX backends support many more image formats (JPG,
TIFF, \dots) but can only be used in GUI mode and produce lower
quality images. The GUI hybrid backends (WXAgg, GTKAgg, Tkagg,
FLTKAgg) have the same limitations and capabilities as Agg.
\item Do you want to produce plots interactively from the python
shell? Because most GUIs have a mainloop, they become unresponsive
to input outside of their mainloop once they are launched. Thus you
often need to use a custom shell to work interactively with a GUI
application from the shell (pycrust for wx, PyShell for gtk). A
notable exception is Tkinter, which can be controlled from a
standard python shell or ipython. At this time, the best backend
for interactive use is TkAgg.\footnote{Fernando Perez, the
ipython developer, is working for a threaded ipython shell for use
with matplotlib and GTK, so this may change in the near future.}
\item What platform do you work most on? Do you want to embed
matplotlib in an application that you distribute across platforms?
Do you need a GUI interface? Each of the python GUIs work on all
major platforms, but some are easier than others to install. Each
have different advantages: GTK is natural for linux and has
excellent looking widgets but is a tough install on OS X. Tkinter
is deployed with most python installations but has primitive looking
widgets. wxpython has native widgets but can be difficult to
install. \textit{Windows users note: the enthought edition of
python from \url{http://www.enthought.com/python} comes with Tkinter
and wxpython included}.
\item What features do you need? Some of the matplotlib features
including alpha blending, antialiasing, images and mathtext are not
ported to all backends. Agg and the GUIAgg hybrids support all
matplotlib features (agg is a core matplotlib backend). postscript,
native gtk and native wx do not support alpha or antialiasing. svg
supports everything except mathtext (which will be added soon
hopefully).
\item Do you need dynamic images such as animation? The GUI backends
vary in their ability to support rapid updating of the image
canvas. GTKAgg is currently the fastest backend for animation,
with FLTKAgg a close second.
\end{itemize}
Once you have decided on which backends you want to install, make sure
you install the GUI required toolkits (and devel versions if you are
using a package manager). Then edit \fname{setup.py} and
\fname{.matplotlibrc} files to reflect these choices as described
below.
\section{Integrated development environments}
\label{sec:ides}
If you work primarily in an integrated development environment such as
idle, pycrust, SciTE, Pythonwin, you will probably want to set your
default backend to be compatible with the GUI your IDE uses. See
Table~\ref{tab:ides} for a summary of the various python IDEs and
their matplotlib compatibility.\footnote{If you have experience with
these or other IDEs and matplotlib backends to help me finish this
table, please contact me or the matplotlib-devel mailing list.}
\begin{table}[htbp]
\centering
\begin{tabular}[t]{|l|l|l|}\hline
IDE & GUI & Backends and Options\\\hline
idle & Tkinter & Works best with TkAgg if idle is launched with -n\\
pycrust & WX & Works best with WX/WXAgg\\
Scintilla and SciTE & GTK & Should work with GTK/GTKAgg backends but untested\\
pythonwin & MFC & Unknown\\\hline
\end{tabular}
\caption{\label{tab:ides}python IDEs and matplotlib compatibility.
}
\end{table}
\section{Interactive}
\label{sec:interactive}
By default, matplotlib defers drawing until the end of the script
because drawing can be an expensive opertation, and in often you don't
want to update the plot every time a single property is changed, only
once after all the properties have changed. But in interactive mode,
eg from the python shell, you usually do want to update the plot with
every command, eg, after changing the xlabel or the marker style of a
line. To do this, you need to set \rc{interactive : True} in your
configuration file; see Section~\ref{sec:matplotlibrc}.
There are many python shells out there: the standard python shell,
ipython, PyShell, pysh, pycrust. Some of these are GUI dependent
(PyShell/pycrust) and some are not (ipython, pysh). As discussed in
backends Section~\ref{sec:backends}, not all shells are compatible
with all matplotlib backends because of GUI mainloop issues. With a
non-GUI python shell such as the standard python shell, ipython or
pysh, the TkAgg backend is the best choice for interactive use. Just
set \rc{backend : TkAgg} and \rc{interactive : True} in your
\fname{.matplotlibrc}file and fire up python. Then
\begin{lstlisting}
# using matplotlib interactively from the python shell
>>> from matplotlib.matlab import *
>>> plot([1,2,3])
>>> xlabel('hi mom')
\end{lstlisting}
\noindent should work out of the box. Note, in batch mode, ie when making
figures from scripts, interactive mode can be slow since it redraws
the figure with each command. So you may want to think carefully
before making this the default behavior.
Unfortunately, due to the 'mainloop' cycle of GUI toolkits, it is not
yet possible to use matplotlib from an arbitrary python shell with the
other GUI backends. Instead, there are custom solutions depending on
the GUI environment in which you use matplotlib; see
\url{http://matplotlib.sourceforge.net/backends.html}. Fernando Perez
is working on a GTK threaded version of ipython for use with the
GTK/GTKAgg backends, which should be nice!
\section{Customization using \fname{.matplotlibrc}}
\label{sec:matplotlibrc}
Almost all of the matplotlib settings and figure properties can be
customized with a plain text file \fname{.matplotlibrc}. This file is
installed with the rest of the matplotlib data (fonts, icons, etc)
into a directory determined by distutils. Before compiling
matplotlib, it resides in the same dir as \fname{setup.py} and will be
copied into your install path. Typical locations for this file are
\begin{verbatim}
C:\Python23\share\matplotlib\.matplotlibrc # windows
/usr/local/share/matplotlib/.matplotlibrc # linux and friends
\end{verbatim}
\noindent By default, the installer will overwrite the existing file in
the install path, so if you want to preserve your's, please move it to
your HOME dir and set the environment variable if necessary.
In the rc file, you can set your backend (Section~\ref{sec:backends}),
your numerix setting (Section~\ref{sec:numerix}), whether you'll be
working interactively (Section~\ref{sec:interactive}) and default
values for most of the figure properties.
\subsection{RC file format}
Blank lines, or lines starting with a comment symbol, are ignored,
as are trailing comments. Other lines must have the format
\begin{lstlisting}
key : val # optional comment
\end{lstlisting}
\noindent where \rc{key} is some property like \rc{backend},
\rc{lines.linewidth}, or \rc{figure.figsize} and \rc{val} is the value
of that property. Example entries for these properties are
\begin{lstlisting}
# this is a comment and is ignored
backend : GTKAgg # the default backend
lines.linewidth : 0.5 # line width in points
figure.figsize : 8, 6 # figure size in inches
\end{lstlisting}
\noindent A complete sample rc file is shown in Appendix~\ref{cha:rc}.
The matplotlib rc values are read into a dictionary \code{rcParams} which
contains the key/value pairs. You can changes these values within a
script by importing this dictionary. For example, to require that a
given script uses numarray, you could do
\begin{lstlisting}
from matplotlib import rcParams
rcParams['numerix'] = 'numarray'
from matplotlib.matlab import *
\end{lstlisting}
\noindent Additionally, the commands \mpldoc{matplotlib.rc} and
\mpldoc{matplotlib.rcdefaults} can be used to dynamically customize
the defaults during a script execution (discussed below).
\subsection{Which rc file is used?}
matplotlib will search for an rc file in the following locations
\begin{itemize}
\item The current directory - this allows you to have a project
specific configuration that differs from your default configuration
\item Your HOME dir. On linux and other UNIX operating systems, this
environment variable is set by default. Windows users can set in
the My Computer properties
\item PATH/.matplotlibrc where PATH is the return value of
\code{matplotlib.get\_data\_path()}. This function looks where
distutils would have installed the file - if it doesn't find it
there, it checks for the environment variable MATPLOTLIBDATA and
uses that if found. The latter should be set if you are installing
matplotlib to a nonstandard location. Eg, if you install matplotlib
with \code{python setup.py build --prefix=/home/jdhunter} then set
matplotlib data to \fname{/home/jdhunter/share/matplotlib.}
\item After all that, if it cannot find your rc file, it will issue a
warning and use defaults. This is not recommended!
\end{itemize}
\section{Installing}
\label{sec:installing}
matplotlib requires at a minimum python 2.2+, Numeric or numarray and
freetype. To get the most out of matplotlib, you will want to build
some of the optional GUI and image extensions, discussed below.
Matplotlib is known to work on linux, unix, win32 and OS X platforms.
\subsection{Compiling matplotlib}
\label{sec:compilng}
You will need to have recent versions of freetype (>= 2.1.7), libpng
and zlib installed on your system. If you are using a package
manager, also make sure the devel versions of these packages are also
installed (eg freetype-devel).
The top of \fname{setup.py} contains some flags controlling which
backends will be built. If you want to use a GUI backend, you will
need either Tkinter, pygtk or wxpython installed on your system, from
src or from a package manager including the devel packages. You can
choose which backends to enable by setting the flags in setup.py, but
the 'auto' flags will work in most cases, as matplotlib tries to find
a GUI and build the backend accordingly. If you know you don't want a
particular backend or extension, you can set that flag to \val{False}.
Most users will want to set \code{BUILD\_AGG = 1} and one or more of
the GUI backends to \val{True}. Exceptions to this are if you know
you don't need a GUI (eg a web server) or you only want to produce
vector graphics.
If you have installed prerequisites to nonstandard places and need to
inform matplotlib where they are, edit setupext.py an add the base
dirs to the 'basedir' dictionary entry for your sys.platform. Eg, if
the header to some required library is in
\fname{/some/path/include/somheader.h}, put \fname{/some/path} in the
basedir list for your platform.
Note, matplotlib works with with Numeric or numarray, but it is
important that you set \code{NUMERIX} in \fname{setup.py} to the array
package you typically use, for efficiency reasons. For performace, it
is critical that the numerix settings in \fname{setup.py} and in your
\fname{.matplotlibrc} file are the same, and are the same as the array
package you typically use.
Note that if you install matplotlib anywhere other than the default
location, you will need to set the \code{MATPLOTLIBDATA} environment
variable to point to the install base dir. Eg, if you install
matplotlib with \code{python setup.py build --prefix=/home/jdhunter}
then set \code{MATPLOTLIBDATA} to\\
\fname{/home/jdhunter/share/matplotlib}.
\subsection{Installing on windows}
If you don't already have python installed, you may want to consider
using the enthought edition of python, which has scipy, Numeric, and
wxpython, plus a lot of other goodies, preinstalled -
\url{http://www.enthought.com/python} . With the enthought edition of
python + matplotlib installer, the following backends should work out
of the box: agg, wx, wxagg, tkagg, ps and svg.
For standard python installations, you will also need to install
either Numeric or numarray in addition to the matplotlib installer.
matplotlib provides installers for Numeric and numarray users. It is
important that you pick the matplotlib installer that corresponds to
your array package. Ie, if you mostly work with numarray arrays, use
the matplotlib numarray installer. matplotlib has a 'numerix' setting
in the matplotlib rc file should make sure this setting corresponds to
your preferred array package; Sections~\ref{sec:numerix} and
\ref{sec:matplotlibrc}. With a standard python + Numeric/numarray +
matplotlib, the following backends should work on windows: agg, tkagg,
ps, svg. If you want others, eg a wx, wxagg, gtk or gtkagg, you'll
need to install the requisite GUI toolkits. This is fairly easy, as
both wxpython and pygtk come with windows friendly installers. The
latter includes an additional requirement of the GTK runtime.
All of the GUI backends run on windows, but TkAgg is probably the best
for interactive use from the standard python shell or ipython. The
windows installer (*.exe) on the download page contains all the code
you need to get up and running. However, there are many examples that
are not included in the windows installer. If you want to try the
many demos that come in the matplotlib src distribution, download the
zip file and look in the examples subdir.
\textbf{Important:} There are known conflicts with some of the
backends with some python IDEs such as pycrust, idle. If you want to
use matplotlib from an IDE, please consult
\url{http://matplotlib.sf.net/backends.html} for compatibility
information. You will have the greatest likelihood of success if you
run the examples from the command shell or by double clicking on them,
rather than from an IDE. If you are interactively generating plots,
your best bet is TkAgg from the standard python shell or ipython.
\subsubsection{OS X}
\label{sec:osx}
All of the backends run on OS X. fink users consult the fink section
below. Another option is \url{http://www.stecf.org/macosxscisoft}
which packages many scientific packages for python on OS X, including
matplotlib, although it is designed for astronomical analysis.
If you want to compile yourself on OS X, make sure you read the
compiling instructions above. You will need to install freetype2,
libpng and zlib via fink or from src. You will also need the base
libraries for a given backend. Eg, if you want to run TkAgg, you will
need a python with Tkinter; if you want to use WxAgg, install
wxpython. See Section~\ref{sec:backends} for a more comprehensive
discussion of the various backend requirements. Edit \fname{setup.py}
to configure the backends you want to build as described above.
\subsection{Package managers: (rpms, apt, fink)}
\subsubsection{RPMS}
\label{sec:rpms}
To build all the backends on a binary linux distro such as redhat, you
ccgneed to install a number of the devel libs (and whatever dependencies
they require), I suggest
\begin{itemize}
\item matplotlib core: zlib, zlib-devel, libpng, libpng-devel,
freetype, freetype-devel, freetype-utils
\item gtk backend: gtk2-devel, gtk+-devel, pygtk2, glib-devel,
pygtk2-devel, gnome-libs-devel, pygtk2-libglade
\item tk backend: tcl, tk, tkinter
\item wx, wxagg backend. The wxpython rpms.
\end{itemize}
\subsubsection{Debian}
\label{sec:debian}
Vittorio Palmisano <redclay@email.it> maintails the debian
packages at \url{http://mentors.debian.net}. He provides the
following instructions
\begin{itemize}
\item add these lines to your /etc/apt/sources.list:
\begin{verbatim}
deb http://mentors.debian.net/debian unstable main contrib non-free
deb-src http://mentors.debian.net/debian unstable main contrib non-free
\end{verbatim}
\item then run
\begin{verbatim}
> apt-get update
> apt-get install python-matplotlib python-matplotlib-doc
\end{verbatim}
\end{itemize}
\subsubsection{fink}
\label{sec:fink}
fink users should use Jeffrey Whitaker's matplotlib fink package,
which supports the GTK, TkAgg, GTKAgg, PS, WX, WXAgg and Agg backends
- \url{http://fink.sourceforge.net/pdb/package.php/matplotlib-py23}.
\chapter{The \matlab\ interface}
\label{cha:matlab_interface}
Although matplotlib has a full object oriented API, the primary way
people create plots is via the matlab interface, which can be imported
with
\begin{lstlisting}
from matplotlib.matlab import *
\end{lstlisting}
\noindent This import command brings in all of the matplotlib code
needed to produce plots, the extra matlab compatible, non-plotting
functions found in \mpldoc{matplotlib.mlab} and all of the
matplotlib.numerix code needed to create and manipulate arrays. The
latter import depends on your \rc{numerix} setting in
\fname{.matplotlibrc}, as described in Sections~\ref{sec:numerix} and
\ref{sec:matplotlibrc}; ie, when you import
\mpldoc{matplotlib.matlab}, you will either get all of Numeric or all
of numarray depending on your \rc{numerix} setting.
matplotlib is organized around figures and axes. The figure contains
an arbitrary number of axes, which can be placed anywhere in the
figure you want, including over other axes. You can directly create
and manage your own figures and axes, but if you don't, matplotlib
will try and do the right thing by automatically creating default
figures and axes for you if you issue a plot command before creating a
figure or axes.
There are two ways of working in the matlab interface: interactively
or in script mode. When working interactively, you want every
plotting command to update the figure. Under the hood, this means
that the canvas is redrawn after every command that affects the
figure. When working in script mode, this is inefficient. In this
case, you only want the figure to be drawn once, either to the GUI
window or saved to a file. To handle these two cases, matplotlib has
an \rc{interactive} setting in \fname{.matplotlibrc}. When
\rc{interactive : True}, the figure will be redrawn with each command.
When \rc{interactive : False}, the figure will be drawn only when
there is a call to \func{show} or \func{savefig}. In the examples
that follow, I'll assume you have set \rc{interactive : True} in your
\fname{.matplotlibrc} file and are working from an interactive python
shell using a compatible backend. Please make sure you have read and
understood Sections~\ref{sec:matplotlibrc}, \ref{sec:backends} and
\ref{sec:ides} before trying these examples.
\section{Simple plots}
\label{sec:simple_plot}
Just about the simplest plot you can create is
\begin{lstlisting}
>>> from matplotlib.matlab import *
>>> plot([1,2,3])
\end{lstlisting}
\noindent I have set my backend to \rc{backend : TkAgg}, which causes
the plot in Figure~\ref{fig:simple_plot_tkagg} to appear, with
navigation controls for interactive panning and zooming.
\fig{3in}{figures/simple_plot_tkagg}{A simple plot shown in the TkAgg
graphical user interface. Navigation controls shown below the
figure provide an easy way to pan and zoom around your figures, and
a save dialog allows you to save your figure after you have set the
pan and zoom.}{fig:simple_plot_tkagg}
I can continue to decorate the plot with labels and titles
\begin{lstlisting}
>>> xlabel('time (s)')
>>> ylabel('volts')
>>> title('A really simple plot')
>>> grid(True)
\end{lstlisting}
\noindent and the updated figure is shown in Figure~\ref{fig:simple_plot_tkagg_labeled}.
\fig{3in}{figures/simple_plot_tkagg_labeled}{A simple plot decorated
with some text labels and an axes grid}{fig:simple_plot_tkagg_labeled}
At this point we're getting a little bored plotting \code{[1,2,3]}.
matplotlib is designed around plotting numerix arrays, and can handle
large arrays efficiently. To create a regularly sampled 1\,Hz sine
wave use the arange and sin methods methods provided by numerix which
produces the plot shown in Figure~\ref{fig:simple_plot_tkagg_sine}.
\begin{lstlisting}
>>> t = arange(0.0, 3.0, 0.05) # in matlab t = [0.0: 0.05: 3.0];
>>> s = sin(2*pi*t)
>>> plot(t,s)
\end{lstlisting}
\fig{3in}{figures/simple_plot_tkagg_sine}{A sine wave added to the
simple plot. This may not be what we wanted. Because the
\func{hold} state was on, the two plots were
superimposed.}{fig:simple_plot_tkagg_sine}
\noindent Note that the two plots are superimposed. matplotlib (and
\matlab) have a \func{hold} state. When hold is on, subsequent
plotting commands are superimposed over previous commands. When hold
is off, the plot is cleared with every plotting command. This is
controlled by the \func{hold} command, which can be called like
\code{hold(True)} or \code{hold(False)}. The default setting is in
\fname{.matplotlibrc} as \rc{axes.hold : True}, which you can change
according to your preferences. To clear the previous plot and reissue
the plot command for just the sine wave, you can use \func{cla} to
clear the current axes and \func{clf} to clear the current figure, or
simply turn the hold state off.
\begin{lstlisting}
>>> hold(False)
>>> plot(t, s)
\end{lstlisting}
\section{More on plot}
\label{sec:plot}
\subsection{Multiple lines}
\label{sec:plot_multiple_lines}
\func{plot} is a versatile command, and will create an arbitrary
number of lines with different line styles and markers. This example
plots a sine wave and a damped exponential using the default line styles
\begin{lstlisting}
>>> clf() # clear the figure
>>> t = arange(0.0, 5.0, 0.05)
>>> s1 = sin(2*pi*t)
>>> s2 = s1 * exp(-t)
>>> plot(t, s1, t, s2)
\end{lstlisting}
\noindent If you plot multiple lines in a single plot command, the
line color will cycle through a list of predefined colors. The
default line color and line style are determined by the rc parameters
\rc{lines.style} and \rc{lines.color}. You can include an optional
third string argument to each line in the plot command, which
specifies any of the line style, marker style and line color. To plot
the above using a green dashed line with circle markers, and a red
dotted line with circle markers, as shown in
Figure~\ref{fig:plot_styles},
\begin{lstlisting}
>>> clf()
>>> plot(t, s1, 'g--o', t, s2, 'r:s')
>>> legend(('sine wave', 'damped exponential'))
\end{lstlisting}
\fig{3in}{figures/plot_styles}{All line plots take an optional third
string argument, which is composed of (optionally) a line color (eg,
'r', 'g', 'k'), a line style (eg, '-', '--', ':') and a line marker
('o', 's', 'd'). The sine wave line (green dashed line with circle
markers) is created with 'g--o'. The \func{legend} command will
automatically create a legend for all the lines in the plot.
}{fig:plot_styles}
\noindent The color part of the format string applies only to the
facecolor of 2D plot markers like circles, triangles, and squares.
The edgecolor of these markers will be determined by the default rc
parameter \rc{lines.markeredgecolor} and can be defined for individual
lines using the methods discussed below.
\subsection{Controlling line properties}
\label{sec:plot_line_props}
In the last section, we showed how to choose the default line
properties using plot format strings. For finer grained control, you
can set any of the attributes of a \mpldoc{matplotlib.lines.Line2D}
instance. There are three ways to do this: using keyword arguments,
calling the line methods directly, or using the \func{set} command.
The line properties are shown in Table~\ref{tab:line_props}.
\begin{table}[htbp]
\centering
\begin{tabular}[t]{|l|l|}\hline
\carg{Property} & \val{Value}\\\hline
\carg{alpha} & The alpha transparency on 0-1 scale\\
\carg{antialiased} & \val{True} or \val{False} - use antialised rendering\\
\carg{color} & A matplotlib color arg\\
\carg{data\_clipping} & Whether to use numeric to clip data\\
\carg{label} & A string optionally used for legend\\
\carg{linestyle} & One of \code{-- : -. -} \\
\carg{linewidth} & A float, the line width in points\\
\carg{marker} & One of \code{$+$ , o . s v x $>$ $<$, etc }\\
\carg{markeredgewidth} & The line width around the marker symbol\\
\carg{markeredgecolor} & The edge color if a marker is used\\
\carg{markerfacecolor} & The face color if a marker is used\\
\carg{markersize} & The size of the marker in points\\\hline
\end{tabular}
\caption{\label{tab:line_props}Line properties; see
\mpldoc{matplotlib.matlab.plot} for more marker
styles}
\end{table}
\subsubsection{Using keyword arguments to control line properties}
\label{sec:plot_kwargs}
You can set any of the line properties listed in
Table~\ref{tab:line_props} using keyword arguments to the plot
command. The following command plots large green diamonds with a red
border
\begin{lstlisting}
>>> plot(t, s1, markersize=15, marker='d', \
... markerfacecolor='g', markeredgecolor='r')
\end{lstlisting}
\subsubsection{Using \func{set} to control line properties}
\label{sec:plot_set_line_props}
You can set any of the line properties listed in
Table~\ref{tab:line_props} using the \func{set} command. Set operates
on the return value of the plot command (a list of lines), so you need
to save the lines. You can use an arbitrary number of key/value pairs
\begin{lstlisting}
>>> lines = plot(t, s1)
>>> set(lines, markersize=15, marker='d', \
... markerfacecolor='g', markeredgecolor='r')
\end{lstlisting}
\noindent \func{set} can either operate on a single instance or a
sequence of instances (in the example code above, \code{lines} is a
length one sequence of lines). Under the hood, if you pass a keyword
arg named \carg{something}, \func{set} looks for a method of the
object called \func{set\_something} and will call it with the value you
pass. If \func{set\_something} does not exist, then an exception will
be raised.
\subsubsection{Using \mpldoc{matplotlib.lines.Line2D} methods}
\label{sec:plot_set_line_methods}
You can also call Line2D methods directly. The return value of plot
is a sequence of \mpldoc{matplotlib.lines.Line2D} instances. Note in
the example below, I use tuple unpacking with the ``,'' to extract the first element
of the sequence as \carg{line}: \code{line, = plot(t, s1)}
\begin{lstlisting}
>>> line, = plot(t, s1)
>>> line.set_markersize(15)
>>> line.set_marker('d')
>>> line.set_markerfacecolor('g')
>>> line.set_markeredgecolor('r')
\end{lstlisting}
\noindent Note, however, that we haven't issued any
\mpldoc{matplotlib.matlab} commands after the initial \func{plot}
command so the figure will not be redrawn even though interactive mode
is set. To trigger a redraw, you can simply resize the figure window
a little or call the \func{draw} method. The fruits of your labors
are shown in Figure~\ref{fig:big_diamonds}.
\begin{lstlisting}
>>> draw()
\end{lstlisting}
\fig{3in}{figures/big_diamonds}{Large green diamonds with red borders,
created with three different recipes.}{fig:big_diamonds}
\subsubsection{Abbreviated method names}
\label{sec:line_abbrevs}
\begin{table}[htbp]
\centering
\begin{tabular}[t]{|l|l|}\hline
\carg{Abbreviation} & \val{Fullname}\\\hline
aa & antialiased\\
c & color\\
ls & linestyle\\
lw & linewidth\\
mec & markeredgecolor\\
mew & markeredgewidth\\
mfc & markerfacecolor\\
ms & markersize\\\hline
\end{tabular}
\caption{\label{tab:line_abbrevs}Abbreviated names for line
properties. You can use any of the line customization methods
above with abbreviated names.}
\end{table}
When working from an interactive python shell, typing
'markerfacecolor' can be a pain -- too many keystrokes. The
\mpldoc{matplotlib.lines.Line2D} class provides a number of
abbreviated method names, listed in Table~\ref{tab:line_abbrevs}.
\noindent Thus you can, for example, call
\begin{lstlisting}
# no antialiasing, thick green markeredge lines
>>> plot(range(10), 'ro', aa=False, mew=2, mec='g')
\end{lstlisting}
\section{Color arguments}
\label{sec:colors}
matplotlib is fairly tolerant of a number of formats for passing color
information. As discussed above, you can use and of the single
character color strings listed in Table~\ref{tab:color_strings}.
Additionally, anywhere a color character string is accepted, you can
also use a grayscale, hex or RGB color argument.
\fig{4in}{figures/color_demo}{Lots of different ways to specify colors
generated from Listing~\ref{lst:color_demo}-- not necessarily
recommended for aesthetic quality!}{fig:color_demo}
\lstinputlisting[caption={Wild and wonderful ways to specify colors;
see Figure~\ref{fig:color_demo}},
label=lst:color_demo]{code/color_demo.py}
\begin{table}[htbp]
\centering
\begin{tabular}[t]{|l|l|}\hline
b & blue\\
g & green\\
r & red\\
c & cyan\\
m & magenta\\
y & yellow\\
k & black\\
w & white\\
0.75 & a grayscale intensity (any float in [0,1]\\
\#2F4F4F & an RGB hex color string, eg, this example is dark slate
gray\\
(0.18, 0.31, 0.31) & an RGB tuple; this is also dark slate gray\\\hline
\end{tabular}
\caption{\label{tab:color_strings}Color format strings, which can be
used to set the line or text properties, eg the line, the marker
edgecolor or marker facecolor. }
\end{table}
\section{Loading and saving data}
\label{sec:loading_data}
\mpldoc{matplotlib.matlab} provides support for loading and saving
ASCII arrays or vectors with the \func{load} and \func{save} command.
\mpldoc{matplotlib.numerix} provides support for loading and saving
binary arrays with the \func{fromstring} and \func{tostring} methods.
\subsection{Loading and saving ASCII data}
\label{sec:ascii_data}
Suppose you have an ASCII file of measured times and voltages like so
\begin{verbatim}
0.0000 0.4911
0.0500 0.5012
0.1000 0.7236
0.1500 1.1756
... and so on
\end{verbatim}
\noindent You can load that data into an array \code{X} with the \func{load}
command. The shape of X is numSamples rows by 2 columns, with the
first column containing the time points and the second column
containing the measured voltages. You can use numerix array indexing
to extract the two columns into the 1D arrays \code{t} and \code{s}
\begin{lstlisting}
X = load('../data/ascii_data.dat')
t = X[:,0] # the first column
s = X[:,1] # the second row
plot(t, s, 'o')
\end{lstlisting}
Likewise, you can save array or vector data in an ASCII file
with the \func{save} command. The following script was used to create
the sample data above
\lstinputlisting{code/gen_ascii_data.py}
\subsection{Loading and saving binary data}
\label{sec:binary_data}
ASCII is bloated and slow for working with large arrays, and so binary
data should be used if performance is a consideration. To save the
array \code{X} in binary form, use the numerix \func{tostring} method
\begin{lstlisting}
# open the file for writing binary and write the binary string
file('../data/binary_data.dat', 'wb').write(X.tostring())
\end{lstlisting}
\noindent This data can later be loaded into a numerix array using
\func{fromstring}. This method takes two arguments, a string and a
data type (note that numarray users can use \func{fromfile} which is
more efficient for importing data directly from a file).
\lstinputlisting{code/load_binary_data.py}
\noindent Note that although Numerix and numarray use different
typecode arguments (Numeric uses strings whereas numarray uses type
objects), the matplotlib.numerix compatibility layer provides symbols
which will work with either \rc{numerix} rc setting.
\subsection{Processing several data files}
\label{sec:multiple_files}
Since python is a programming language \textit{par excellence}, it is
easy to process data in batch. When I started the gradual transition
from a full time matlab user to a full time python user, I began
processing my data in python and saving the results to data files for
plotting in matlab. When that became too cumbersome, I decided to
write matplotlib so I could have all the functionality I needed in one
environment. Here is a brief example showing how to iterate over
several data files, named \fname{basename001.dat, basename002.dat,
basename003.dat, ... basename100.dat} and plot all of the traces to
the same axes. I'll assume for this example that each file is a 1D
ASCII array, which I can load with the \func{load} command.
\begin{lstlisting}
hold(True) # set the hold state to be on
for i in range(1,101): #start at 1, end at 100
fname = 'basename%03d.dat'%i # %03d pads the integers with zeros
x = load(fname)
plot(x)
\end{lstlisting}
\section{axes and figures}
\label{sec:axes_and_figures}
All the examples thus far used \textit{implicit} figure and axes
creation. You can use the functions \func{figure}, \func{subplot},
and \func{axes} to explicitly control this process. Let's take a look
at what happens under the hood when you issue the commands
\begin{lstlisting}
>>> from matplotlib.matlab import *
>>> plot([1,2,3])
\end{lstlisting}
When plot is called, the matlab interface makes a call to \func{gca()}
(``get current axes'') to get a reference to the current axes.
\func{gca} in turn, makes a call to \func{gcf} to get a reference to
the current figure. \func{gcf}, finding that no figure has been
created, creates the default figure \code{figure()} and returns it.
\func{gca} will then return the current axes of that figure if it
exists, or create the default axes \code{subplot(111)} if it does
not. Thus the code above is equivalent to
\begin{lstlisting}
>>> from matplotlib.matlab import *
>>> figure()
>>> subplot(111)
>>> plot([1,2,3])
\end{lstlisting}
\subsection{\func{figure}}
\label{sec:figure}
You can create and manage an arbitrary number of figures using the
\func{figure} command. The standard way to create a figure is to
number them from $1 \dots N$. A call to \code{figure(1)} creates
figure 1 if it does not exist, makes figure 1 active (\func{gcf} will
return a reference to it), and returns the
\mpldoc{matplotlib.figure.Figure} instance. The syntax of the
\func{figure} command is
\begin{lstlisting}
def figure(num=1,
figsize = None, # defaults to rc figure.figsize
dpi = None, # defaults to rc figure.dpi
facecolor = None, # defaults to rc figure.facecolor
edgecolor = None, # defaults to rc figure.edgecolor
frameon = True, # whether to draw the figure frame
):
\end{lstlisting}
\carg{figsize} gives the figure size in inches and is width by
height. Eg, to create a figure 12 inches wide and 2 inches high, you
can call \code{figure(figsize=(12,2))}. \carg{dpi} gives the dots per
inch of your display device. Increasing this number effectively
creates a higher resolution figure. \carg{facecolor} and
\carg{edgecolor} determine the face and edge color of the figure
rectangular background. This is what gives the figure a gray
background in the GUI figures such as
Figure~\ref{fig:simple_plot_tkagg}. You can turn this background
completely off by setting \code{frameon=False}. The default for
saving figures is to have a white face and edge color, and all of
these properties can be customized using the rc parameters
\rc{figure.*} and \rc{savefig.*}.
In typical usage, you will only provide the figure number, and let
your rc parameters govern the other figure attributes
\begin{lstlisting}
>>> figure(1)
>>> plot([1,2,3])
>>> figure(2)
>>> plot([4,5,6])
>>> title('big numbers') # figure 2 title
>>> figure(1)
>>> title('small numbers') # figure 1 title
\end{lstlisting}
You can close a figure simply by clicking on the close ``x'' in the
GUI window, or by issuing the \func{close} command. \func{close} can
be used to close the current figure, a figure referenced by number, a
given figure instance, or all figures
\begin{itemize}
\item \code{close()} by itself closes the current figure
\item \code{close(num)} closes figure number \val{num}
\item \code{close(num)} closes figure number \val{num}
\item \code{close(fig)} where \val{fig} is a figure instance closes
that figure
\item \code{close('all')} closes all the figure windows
\end{itemize}
\noindent If you close a figure directly, eg \code{close(2)} the
previous current figure is restored to the current figure. \func{clf}
is used to clear the current figure without closing it.
If you save the return value of the figure command, you can call any
of the methods provided by \mpldoc{matplotlib.figure.Figure}, for
example, you can set the figure facecolor
\begin{lstlisting}
>>> fig = figure(1)
>>> fig.set_facecolor('g')
\end{lstlisting}
or use \func{set} for the same purpose
\begin{lstlisting}
>>> set(fig, facecolor='g')
\end{lstlisting}
\subsection{\func{subplot}}
\label{sec:subplot}
\func{axes} and \func{subplot} are both used to create axes in a
figure. \func{subplot} is used more commonly, and creates axes
assuming a regular grid of axes \carg{numRows} by \carg{numCols}.
For example, to create two rows and one column of axes, you would use
\code{subplot(211)} to create the upper axes and \code{subplot(212)}
to create the lower axes. The last digit counts across the rows.
\fig{4in}{figures/subplot_demo}{Multiple rows of axes created with the
subplot command, as shown in
Listing~\ref{lst:subplot_demo}}{fig:subplot_demo}
\lstinputlisting[caption={Generating multiple axes with subplot; see Figure~\ref{fig:subplot_demo}}, label=lst:subplot_demo]{code/subplot_demo.py}
\noindent Likewise, to create two columns and one row of axes, you would use
\code{subplot(121)} to create the left axes and \code{subplot(122)} to
create the right axes. If the total number of axes exceeds single
digits, use comma separated arguments to subplot. For example, the
lower right panel of a 3 x 4 grid of axes is created with
\code{subplot(3,4,12)}. matplotlib uses matlab style indexing in
creating figures and axes, so \code{subplot(3,4,1)} is the first
subplot, not \code{subplot(3,4,0)}.
The subplot command returns a \mpldoc{matplotlib.axes.Subplot}
instance, which is derived from \mpldoc{matplotlib.axes.Axes}. Thus
you can call and Axes or Subplot method on it. When creating multiple
subplots with the same axes, for example the same time axes, sometimes
it helps to turn off the x tick labeling for all but the lowest plot.
Here is some example code
\begin{lstlisting}
subplot(211)
plot([1,2,3], [1,2,3])
set(gca(), 'xticklabels', [])
subplot(212)
plot([1,2,3], [1,4,9])
\end{lstlisting}
Likewise, with multiple columns and shared y axes, you may want turn
off the ytick labels for all but the first row. The subplot command
returns a \mpldoc{matplotlib.axes.Subplot} instance, which is derived
from \mpldoc{matplotlib.axes.Axes}. Thus you can call and Axes or
Subplot method on it. Subplot defines some helper methods
(\func{is\_first\_row}, \func{is\_first\_col}, \func{is\_last\_row},
\func{is\_last\_col}, to help you conditionally set subplot properties,
eg
\begin{lstlisting}
cnt = 0
for i in range(numRows):
for j in range(numCols):
cnt += 1
ax = subplot(numRows, numCols, cnt)
plot(blah, blah)
if ax.is_last_row() : xlabel('time (s)')
if ax.is_first_col() : ylabel('volts')
\end{lstlisting}
Here is some example code to create multiple figures and axes, using
the \func{figure} and \func{subplot} command to control the current
figure and axes.
\lstinputlisting{code/multiple_figures.py}
\subsection{\func{axes}}
\label{sec:axes}
When you need a finer grained control over axes placement than
afforded by \func{subplot}, use the func{axes} command. The
\func{axes} command in initialized with a rectangle code{[left,
bottom, width, height]} in relative figure coordinates. \code{left,
bottom = (0, 0)} is the bottom left of the of the figure canvas, and
a width/height of 1 spans the figure width/height. This to create an
axes that entirely fills the figure canvas, you would do \code{axes([0,
1, 0, 1])}. This may not be a good idea, because it leaves no room
for text labels. \code{axes([0.25, 0.25, 0.5, 0.5])} creates an axes
offset by one quarter of the figure width and height on all sides.
There are several ways to use the \func{axes} command; in all cases, a
\mpldoc{matplotlib.axes.Axes} instance is returned
\begin{itemize}
\item \code{axes()} by itself creates a default full
\code{subplot(111)} window axis
\item \code{axes(rect, axisbg='w')} where \code{rect=[left, bottom,
width, height]} in normalized (0,1) units. \carg{axisbg} is the
background color for the axis, default white.
\item \code{axes(ax)} where \carg{ax} is an axes instance makes
\carg{ax} current.
\end{itemize}
\noindent \func{gca} returns the current axes instance and \func{cla}
clears the current axes. You can use the \func{axes} command lay the
axes exactly where you want them, including to overlaying one axes on
top of another, as in this example
\fig{4in}{figures/axes_demo}{Using the \func{axes} command to create
inset axes over another axes.}{fig:axes_demo}
\lstinputlisting{code/axes_demo.py}
\section{Text}
\label{sec:text}
matplotlib has excellent text support, including newline separated
text with arbitrary rotations and mathematical expressions. freetype2
support produces very nice, antialiased fonts, that look good even at
small raster sizes. It includes its own font\_manager, thanks to Paul
Barrett, which implements a cross platform, W3C compliant font finding
algorithm. You have total control over every text property (font
size, font weight, text location and color, etc) with sensible
defaults set in the rc file. And significantly for those interested
in mathematical or scientific figures, matplotlib implements a large
number of \TeX\ math symbols and commands, to support mathematical
expressions anywhere in your figure. To get the most out of text in
matplotlib, you should use a backend that supports freetype2 and
mathtext, notably all the *Agg backends (see Section~{ref:backends}).
\subsection{Basic text commands}
\label{sec:basic_text}
The following commands are used to create text in the maplotlib.matlab
interface
\begin{itemize}
\item \func{xlabel(s)} - add a label \carg{s} to the x axis
\item \func{ylabel(s)} - add a label \carg{s} to the y axis
\item \func{title(s)} - add a title \carg{s} to the axes
\item \func{text(x, y, s)} - add text \carg{s} to the axes at
\carg{x}, \carg{y} in data coords
\item \func{figtext(x, y, s)} - add text to the figure at \carg{x},
\carg{y} in relative 0-1 figure coords
\end{itemize}
\subsection{Text properties}
\label{sec:text_props}
The text properties are listed in Table~\ref{tab:text_props}. As with
lines, there are three ways to set text properties: using keyword
arguments to a text command, calling \func{set} on a text instance or
a sequence of text instances, or calling an instance method on a text
instance. These three are illustrated below
\begin{lstlisting}
# keyword args
>>> xlabel('time (s)', color='r', size=16)
>>> title('Fun with text', horizontalalignment='left')
# use set
>>> labels = get(gca(), 'xticklabels')
>>> set(labels, 'color', 'g', rotation=45)
# instance methods
>>> l = ylabel('volts')
>>> l.set_weight('bold')
\end{lstlisting}
\begin{table}[htbp]
\centering
\begin{tabular}[t]{|l|l|}\hline
\carg{Property} & Value\\\hline
\carg{alpha} & The alpha transparency on 0-1 scale\\
\carg{color} & A matplotlib color arg\\
\carg{family} & set the font family, eg 'sans-serif', 'cursive', 'fantasy'\\
\carg{fontangle} & the font slant, one of 'normal', 'italic', 'oblique'\\
\carg{horizontalalignment} & 'left', 'right' or 'center'\\
\carg{multialignment} & 'left', 'right' or 'center'
only for multiline strings\\
\carg{name} & the font name, eg, 'Sans', 'Courier', 'Helvetica'\\
\carg{position} & the x,y location\\
\carg{variant} & the font variant, eg 'normal', 'small-caps'\\
\carg{rotation} & the angle in degrees for rotated text\\
\carg{size} & the fontsize in points, eg, 8, 10, 12\\
\carg{style} & the font style, one of 'normal', 'italic',
'oblique'\\
\carg{text} & set the text string itself\\
\carg{verticalalignment} & 'top', 'bottom' or 'center'\\
\carg{weight} & the font weight, eg 'normal', 'bold', 'heavy',
'light'\\\hline
\end{tabular}
\caption{\label{tab:text_props}Properties of
\mpldoc{matplotlib.text.Text}}
\end{table}
\noindent See the example
\url{http://matplotlib.sourceforge.net/examples/fonts_demo_kw.py}
which makes extensive use of font properties for more information.
See also Chapter~\ref{cha:font_finding} for more discussion of the
font finder algorithm and the meaning of these properties.
\subsection{Text layout}
\label{sec:text_layout}
You can layout text with the alignment arguments
\carg{horizontalalignment}, \carg{verticalalignment}, and
\carg{multialignment}. \carg{horizontalalignment} controls whether
the x positional argument for the text indicates the left, center or
right side of the text bounding box. \carg{verticalalignment} controls
whether the y positional argument for the text indicates the bottom,
center or top side of the text bounding box. \carg{multialignment},
for newline separated strings only, controls whether the different
lines are left, center or right justified. Here is an example which
uses the \func{text} command to show the various alignment
possibilities. The use of \code{transform=ax.transAxes} throughout
the code indicates that the coordinates are given relative to the axes
bounding box, with 0,0 being the lower left of the axes and 1,1 the
upper right.
\fig{6in}{figures/alignment_demo}{Aligning text with
\carg{horizontalalignment}, \carg{verticalalignment}, and
\carg{multialignment} options to the \func{text} command.}{fig:align_text}
\lstinputlisting{code/alignment_demo.py}
\subsection{mathtext}
\label{sec:mathtext}
matplotlib supports \TeX\ mathematical expressions anywhere a text
string can be used, as long as the string is delimited by ``\$'' on
both sides, as in $\mathtt{r'\$5\backslash lambda\$'}$; embedded
mathtext strings, such as in $\mathtt{r'The answer is \$5\backslash
lambda\$'}$ are not currently supported. A large set of the \TeX\
symbols from the computer modern fonts are provided. Subscripting and
superscripting are supported, as well as the over/under style of
subscripting with $\mathtt{\backslash sum}$, $\mathtt{\backslash int}$
etc.
Note that matplotlib does not use or require that \TeX\ be installed on
your system, as it does not use it. Rather, it uses the parsing
module \fname{pyparsing} to parse the \TeX\ expression, and does the
layout manually in the \mpldoc{matplotlib.mathtext} module using the
font information provided by \mpldoc{matplotlib.ft2font}.
\noindent The spacing elements $\backslash/$ and $\mathtt{\backslash
hspace\{num\}}$ are provided. $\backslash /$ inserts a small space,
and $\mathtt{\backslash hspace\{num\}}$ inserts a fraction of the
current fontsize. Eg, if \code{num=0.5} and the fontsize is 12.0,
$\mathtt{\backslash hspace\{0.5\}}$ inserts 6 points of space.
\subsubsection{Licensing}
\label{sec:mathtext_license}
The computer modern fonts this package uses are part of the BaKoMa
fonts, which are (in my understanding) free for noncommercial use.
For commercial use, please consult the licenses in fonts/ttf and the
author Basil K. Malyshev - see also
\url{http://www.mozilla.org/projects/mathml/fonts/encoding/license-bakoma.txt}
and the file BaKoMa-CM.Fonts in the matplotlib fonts dir.
Note that all the code in this module is distributed under the
matplotlib license, and a truly free implementation of mathtext for
either freetype or ps would simply require deriving another concrete
implementation from the Fonts class defined in this module which used
free fonts.
\subsubsection{Using mathtext}
Any text element can use math text. You need to use raw strings
(preceed the quotes with an \code{r}), and surround the string text
with dollar signs, as in \TeX.
\begin{lstlisting}
# plain text
title('alpha > beta')
# math text
title(r'$\alpha > \beta$')
\end{lstlisting}
\noindent To make subscripts and superscripts use the underscore and caret
symbols, as in
\begin{lstlisting}
title(r'$\alpha_i > \beta^i$')
\end{lstlisting}
You can also use a large number of the \TeX\ symbols, as in
$\mathtt{\backslash infty}$, $\mathtt{\backslash leftarrow}$,
$\mathtt{\backslash sum}$, $\mathtt{\backslash int}$; see
Appendix~\ref{cha:math_symbols} for a complete list. The over/under
subscript/superscript style is also supported. To write the sum of
$x_i$ from 0 to $\infty$ ($\sum_{i=0}^\infty x_i$), you could do
\begin{lstlisting}
text(1, -0.6, r'$\sum_{i=0}^\infty x_i$')
\end{lstlisting}
The default font is \textit{italics} for mathematical symbols. To
change fonts, eg, to write 'sin' in a \textrm{roman font}, enclose the
text in a font command, as in
\begin{lstlisting}
text(1,2, r's(t) = $\cal{A}\rm{sin}(2 \omega t)$')
\end{lstlisting}
\noindent Here '$s$' and '$t$' are variable in italics font (default),
'$\mathrm{sin}$' is in roman font, and the amplitude '$\mathcal{A}$'
is in caligraphy font. The fonts $\mathtt{\backslash cal}$,
$\mathtt{\backslash rm}$, $\mathtt{\backslash it}$ and
$\mathtt{\backslash tt}$ are allowed.
Fairly complex \TeX\ expressions render correctly; you can compare the
expression
\begin{verbatim}
s = r'$\cal{R}\prod_{i=\alpha}^\infty a_i\rm{sin}(2 \pi f x_i)$'
\end{verbatim}
\noindent rendered by \TeX\ below and by matplotlib in
Figure~\ref{fig:mathtext_demo}.
\begin{equation}
\mathcal{R}\prod_{i=\alpha}^\infty a_i\mathrm{sin}(2 \pi f x_i)
\end{equation}
\fig{4in}{figures/mathtext_demo}{Incorpating \TeX\ expressions into
your figure.}{fig:mathtext_demo}
\lstinputlisting{code/mathtext_demo.py}
\section{Images}
\label{sec:images}
matplotlib provides support for working with raw image data in numerix
arrays. Currently, there is no support for loading image data from
image files such as PNG, TIFF or JPEG, though this is on the TODO
list. If you need to load data from existing image files, one good
solution is to use The Python Imaging Library to load the data and
convert this to a numerix array - see Recipe~\ref{cbook:image_files}.
The following examples will assume you have your image data loaded
into a numerix array, either luminance (MxN), RGB (MxNx3) or RGBA
(MxNx4).
\subsection{Axes images}
\label{sec:image_axes}
An axes image is created with \code{im = imshow(X)} where
\carg{X} is a numerix array an \carg{im} is a
\mpldoc{matplotlib.image.AxesImage} instance. The image is rescaled to fit
into the current axes box. Here is some example code to display an
image
\lstinputlisting{code/simple_imshow.py}
\noindent \func{imshow} a command in the \mpldoc{matplotlib.matlab}
interface. This is a thin wrapper of the
\mpldoc{matplotlib.Axes.imshow} method, which can be called from any
Axes instance, eg \code{ax.imshow(X)}.
There are two parameters that determine how the image is resampled
into the axes bounding box: \carg{interpolation} and \carg{aspect}.
The following \carg{interpolation} schemes are available:
\val{bicubic, bilinear, blackman100, blackman256, blackman64, nearest,
sinc144, sinc256, sinc64, spline16, and spline36}. The default
interpolation method is given by the value of \rc{image.interpolation}
in your \fname{.matplotlibrc} file. \carg{aspect} can be either
\val{preserve} or \val{free} which will constrain the aspect ratio of
the image or not, respectively. The default aspect setting is given
by the value of the rc parameter \rc{image.aspect}.
The full syntax of the \func{imshow} command is
\begin{lstlisting}
imshow(X, # the numerix array
cmap = None, # the matplotlib.colors.Colormap instance
norm = None, # the normalization instance
aspect=None, # the aspect setting
interpolation=None, # the interpolation method
alpha=1.0, # the alpha transparency value
vmin = None, # the min for image scaling
vmax = None, # the max for image scaling
origin=None): # the image origin
\end{lstlisting}
When \val{None}, these parameters will assume a default value, in
many cases determined by the rc setting. The meaning of \carg{cmap,
norm, vmin, vmax, and origin} will be explained in sections below.
The following shows a simple command which creates an image using
bilinear interpolation, shown in Figure~\ref{fig:image_demo}.
\fig{4in}{figures/image_demo}{Simple axes image}{fig:image_demo}
\lstinputlisting{code/image_demo.py}
You can create an arbitrary number of axes images inside a single
axes, and these will be composed via alpha blending. However, if you
want to blend several images, you must make sure that the
\func{hold} state is \val{True} and that the alpha of the
layered images is less than 1.0; if alpha=1.0 then the image on top
will totally obscure the images below. Because the image blending is
done using antigrain (regardless of your backend choice), you can
blend images even on backends which don't support alpha (eg,
postscript). This is because the alpha blending is done in the
frontend and the blended image is transferred directly to the backend
as an RGB pixel array. See Recipe~\ref{cbook:layer_images} for an example of
how to layer images.
\subsection{Figure images}
\label{sec:image_figure}
Often times you want to be able to look at your raw image data
directly, without interpolation. This is the function of figure
images, which do a pixel-by-pixel transfer of your image data to the
figure canvas \footnote{If you want a resampled image to occupy the
full space of the figure canvas, you can achieve this by specifying
a custom axes that fills the figure canvas \code{axes([0, 1, 0,
1])} and using \func{imshow}.}. Figure images are drawn first,
and thus can become the background of other matplotlib drawing
commands.
In the matlab interface, figure images are created with the
\func{figimage} command, which unlike \func{imshow}, does not
accept an \carg{interpolation} or \carg{aspect} keyword argument
because no image resampling is used. If the pixel extent of the
figure image extends beyond the figure canvas, the image will simply
be truncated. The basic syntax is \code{figimage(X, xo=0, yo=0)}
where X is luminance (MxN), RGB (MxNx3) or RGBA (MxNx4) numerix array
and \carg{xo}, \carg{yo} are pixel offsets from the origin (see
Section~\ref{sec:image_origin}). You can use \func{figimage} to create a
figure image that fills the entire canvas with no x or y offsets, or
you can make multiple calls to \func{figimage} with different x and
y offsets to create a mosaic of images, as shown in
Recipe~\ref{cbook:figure_mosaic}.
The full syntax of the \func{figimage} command is
\begin{lstlisting}
figimage(X, # the numerix array
xo=0, # the x offset
yo=0, # the y offset
alpha=1.0, # the alpha transparency
norm=None, # the matplotlib.colors.normalization instance
cmap=None, # the matplotlib.colors.Colormap instance
vmin=None, # the min for image scaling
vmax=None, # the max for image scaling
origin=None) # the image origin
\end{lstlisting}
The \carg{cmap, norm, vmin, vmax} and \carg{origin} arguments are
explained in the sections below.
\mpldoc{matplotlib.matlab.figimage} is a thin wrapper of
\mpldoc{matplotlib.figure.figimage} and you can generate figure images
directly with the pythonic API using \code{fig.figimage(X)} where
fig is a Figure instance.
\subsection{Scaling and color mapping}
\label{sec:image_to_rgba}
In addition to supporting raw image RGB and RGBA formats, matplotlib
will scale and map luminance data for MxN float (luminance) arrays.
The conversion from luminance data to RGBA occurs in two steps:
scaling and color mapping.
\textit{Scaling} is the process of normalizing an MxN floating point
array to the 0,1 interval, by mapping \carg{vmin} to 0.0 and
\carg{vmax} to 1.0, where \carg{vmin} and \carg{vmax} are user defined
parameters. If either are \val{None}, the min and max of the image
data will be used, respectively. Scaling is handled by a
\mpldoc{matplotlib.colors.normalization} instance, which defaults to
\code{normalization(vmin=None, vmax=None)} - ie, the default is to
scale the image so that the minimum of the luminance array is zero and
the maximum of the luminance array is one.
Typically, you will not create a normalization instance yourself, but
may set \carg{vmin} or \carg{vmax} in the keyword arguments of the
image creation function. In this case, a normalization instance is
created for you, and your vmin, vmax settings are applied. If you do
supply a normalization instance for the \carg{norm} argument,
\carg{vmin} and \carg{vmax} will be ignored. See
Table~\ref{tab:image_norms} for some examples of image normalization
commands and their interpretation.
\begin{table}[htbp]
\centering
\begin{tabular}[t]{ll}
command& interpretation\\
\prompt{imshow(X)} &
$X \leq \mathrm{min}(X) \rightarrow 0 $ and $X \geq \mathrm{max}(X) \rightarrow 1$\\
\prompt{imshow(X, vmax=10)} &
$X \leq \mathrm{min}(X) \rightarrow 0 $ and $X \geq 10 \rightarrow 1$\\
\prompt{imshow(X, vmin=0, vmax=10)} &
$X \leq 0 \rightarrow 0 $ and $X \geq 10 \rightarrow 1$\\
\prompt{anorm=normalize(2,8)} & \\
\prompt{imshow(X, norm=anorm)} &
$X \leq 2 \rightarrow 0 $ and $X \geq 8 \rightarrow 1$\\
\end{tabular}
\caption{\label{tab:image_norms}Example image normalization commands
and their interpretation}
\end{table}
Once the luminance data are normalized, they color mapper transforms
the normalized data to RGBA using a
\mpldoc{matplotlib.colors.Colormap} instance. Common colormaps are
defined in \mpldoc{matplotlib.cm}, including \code{cm.jet} and
\code{cm.gray}. If the cmap argument to an image command is
\val{None}, the default is given by he rc parameter \rc{image.cmap}.
The keyword arguments \carg{cmap, norm, vmin, vmax} control color
mapping and scaling in the image construction commands. Once the
images have been created, several commands exist to interactively
control the color map of the current image. Like the current figure
(\func{gcf}) and the current axes (\func{gca}), matplotlib keeps
track of the current image (\func{gci}) to determine which image to
apply the commands which affect image properties. To interactively
set the image normalization limits, use \code{clim(vmin=None,
vmax=None)}, where \carg{vmin} and \carg{vmax} have the same meaning
as above. To interactively change the colormap, use \func{jet} or
\func{gray} (More colormaps and colormap commands are planned)..
These latter commands not only change the colormap of the current
image, they also set the default for future images.
For quantitative plotting of pseduocolor images, use the
\func{colorbar} function to provide a colorbar associated with the
iamge, Here is an example interactive session controlling image
scaling and color mapping with a colorbar
\begin{lstlisting}
>>> imshow(X) # plot the luminance image X
>>> clim(-1,2) # scale the image
>>> jet() # use colormap jet
>>> colorbar() # add a colorbar to the current axes
>>> gray() # use grayscale; image and colorbar are updated
\end{lstlisting}
The image scaling and color mapping are handled by the mixin base
class \mpldoc{matplotlib.colors.ScalarMappable}.
\subsection{Image origin}
\label{sec:image_origin}
Depending on your data, it may be more natural to plot your data with
the image origin up (\code{X[0,0]} is upper left) or down
(\code{X[0,0]} is lower left). matplotlib supports these two modes
with the \carg{origin} parameter, which can be supplied as an optional
keyword argument to the image commands \func{imshow} and
\func{figimage} with the default set by the rc parameter
\rc{image.origin}. To plot an image with the origin in the upper
left, pass \code{origin='upper'} and with the image in the lower left,
pass \code{origin='lower'}, as shown in Figure~\ref{fig:image_origin}.
\fig{4in}{figures/image_origin}{Controlling the image origin with the
\carg{origin} keyword argument to \func{imshow} and
\func{figimage}.}{fig:image_origin}
\lstinputlisting{code/image_origin.py}
\section{Bar charts, histograms and errorbar plots}
\label{sec:barcharts}
\section{Pseudocolor and scatter plots}
\label{sec:pcolor_scatter}
\section{Spectral analysis}
\label{sec:spectral}
\section{Axis properties}
\label{sec:axis_props}
\section{Legends and tables}
\label{sec:legends_and_tables}
\section{Navigation}
\label{sec:navigation}
matplotlib comes with two navigation toolbars for the graphical user
interfaces: classic and toolbar2. You can use these to change the
view limits of the axes in the figure. toolbar2 superceeds classic
and was designed to overcome shortcomings of the classic toolbar. The
default toolbar is determined by the \rc{toolbar} parameter in
\fname{.matplotlibrc}.
\subsection{Classic toolbar}
\label{sec:toolbar_classic}
You can pan and zoom on the X and Y axis for any combination of the
axes that are plotted. If you have a wheel mouse, you can move
bidirectionally by scrolling the wheel over the controls. For
examples, the wheel mouse can be used to pan left or right by
scrolling over either of the left arrow or right arrow buttons, so you
never have to move the mouse to pan the x-axis left and right. If you
don't have a wheel mouse, buy one!
The left widget that says 'All' on the controls on the bottom of
Figure~\ref{fig:toolbar_classic} is a drop down menu used to select
which axes the controls affect. You can select all, none, single, or
combinations of axes. The first set of 4 controls are used to pan
left, pan right, zoom in and zoom out on the x axes. The second set
are used to pan up, pan down, zoom in and zoom out on the y axes. The
remaining buttons are used to redraw the figure, save (PNG or JPEG)
the figure, or to close the figure window.
\fig{4in}{figures/toolbar_classic}{The classic toolbar, discussed
in Section~\ref{sec:toolbar_classic}}{fig:toolbar_classic}
\subsection{toolbar2}
\label{sec:toolbar_toolbar2}
The toolbar2 buttons (see Figure~\ref{fig:toolbar_toolbar2} behave
very differently from the classic the classic matplotlib toolbar (else
why introduce a new one!) despite the visual similarity of the forward
and back buttons.
The \texttt{Forward} and \texttt{Back} buttons are akin to the web browser
forward and back buttons. They are used to navigate back and forth
between previously defined views. They have no meaning unless you
have already navigated somewhere else using the pan and zoom buttons.
This is analogous to trying to click 'back' on your web browser before
visiting a new page. Nothing happens. \texttt{Home} always takes you to
the first view. For \texttt{Home}, \texttt{Forward} and \texttt{Back}, think web
browser where data views are web pages. Use the \texttt{Pan/Zoom} and
\texttt{Zoom to rectangle} buttons, discussed below, to define new views.
The \texttt{Pan/Zoom} button has two modes: pan and zoom. Click this
toolbar button to activate this mode. Then put your mouse somewhere
over an axes.
\begin{itemize}
\item Mode 1: Press the left mouse button and hold it, dragging it to
a new position. When you release it, the data under the point where
you pressed will be moved to the point where you released. If you
press 'x' or 'y' while panning, the motion will be contrained to the
x or y axis, respectively
\item Mode 2: Press the right mouse button, dragging it to a new
position. The x axis will be zoomed in proportionate to the
rightward movement and zoomed out proportionate to the leftward
movement. Ditto for the yaxis and up/down motions. The point under
your mouse when you begin the zoom should remain in place, allowing
you to zoom to an arbitrary point in the figure. You can use the
modifier keys 'x', 'y' or 'CONTROL' to constrain the zoom to the x
axes, the y axes, or aspect ratio preserve, respectively.
\end{itemize}
The \texttt{Zoom to rectangle} button: Click this toolbar button to
activate this mode. Put your mouse somewhere over and axes and press
the left mouse button. Drag the mouse while holding the button to a
new location and release. The axes view limits will be zoomed to the
rectangle you have defined. There is also an experimental 'zoom out
to rectangle' in this mode with the right button, which will place
your entire axes in the region defined by the zoom out rectangle.
The \texttt{Save} button: click this button to launch a file save
dialog. All the *Agg backends know how to save the following image
types: PNG, PS, EPS, SVG. There is no support currently in Agg for
writing to JPEG, TIFF (the regular wx and gtk backends handle these
types). It is possible to use matplotlib/agg + PIL to convert agg
images to one of these other formats if required. I can provide a
recipe for you. I prefer PNG over JPG and TIFF, which is why I
haven't worked too hard to include these other image formats in agg.
\fig{4in}{figures/toolbar_toolbar2}{The newfangled toolbar2, discussed
in Section~\ref{sec:toolbar_toolbar2}}{fig:toolbar_toolbar2}
\section{Event handling}
\label{sec:events}
When visualizing data, it's often helpful to get some interactive
input from the user. All graphical user interfaces (GUIs) provide
event handling to determine things like key presses, mouse position,
and button clicks. matplotlib supports a number of GUIs, and provides
an interface to the GUI event handling via the \func{mpl\_connect} and
\func{mpl\_disconnect} methods of the matlab interface (API users will
probably want to use their GUIs event handling directly, but do have
the option of using their \mpldoc{FigureCanvas.mpl\_connect} method).
matplotlib uses a callback event handling mechanism. The basic idea
is that you register an event that you want to listen for, and the
figure canvas, will call a user defined function when that event
occurs. For example, if you want to know where the user clicks a
mouse on your figure, you could define a function
\begin{lstlisting}
# this function will be called with every click
def click(event):
print 'you clicked', event.x, event.y
# register this function with the event handler
mpl_connect('button_press_event', click)}.
\end{lstlisting}
\noindent Then
whenever the user clicks anywhere on the figure canvas, your function
will be called and passed a \mpldoc{matplotlib.backend\_bases.MplEvent}
instance. The event instance will have the following attributes
defined.
\begin{table}[htbp]
\centering
\begin{tabular}[t]{|l|l|}\hline
\carg{Property} & \val{Meaning}\\\hline
\carg{x} & x position - pixels from left of canvas\\
\carg{y} & y position - pixels from bottom of canvas\\
\carg{button} & button pressed None, 1, 2, 3\\
\carg{inaxes} & the Axes instance if mouse is over axes (or None)\\
\carg{xdata} & x coord of mouse in data coords (None if mouse
isn't over axes)\\
\carg{ydata} & y coord of mouse in data coords (None if mouse
isn't over axes)\\
\carg{name} & The string name of the event\\
\carg{canvas} & The FigureCanvas instance the event occured in\\
\carg{key} & The key press if any, eg 'a', 'b', '1'. Also
records 'control and 'shift'\\\hline
\end{tabular}
\caption{\label{tab:events}The event attributes}
\end{table}
\noindent You can connect to the following events: 'button\_press\_event',
'button\_release\_event', 'motion\_notify\_event'.
Here's an example to get the mouse location in data coordinates as the
mouse moves
\lstinputlisting{code/coords_demo.py}
\section{Dynamic customizations}
\label{sec:rc_command}
\chapter{Font finding and properties}
\label{cha:font_finding}
\mpldoc{matplotlib.fonts.font\_manager} is module for finding,
managing, and using fonts across-platforms. This module provides a
single FontManager that can be shared across backends and platforms.
The findfont() method returns the best TrueType (TTF) font file in the
local or system font path that matches the specified FontProperties.
The FontManager also handles Adobe Font Metrics (AFM) font files for
use by the PostScript backend.
The design is based on the W3C Cascading Style Sheet, Level 1 (CSS1)
font specification (\url{http://www.w3.org/TR/1998/REC-CSS2-19980512}).
Future versions may implement the Level 2 or 2.1 specifications.
The \rc{font.family} property has five values: 'serif' (e.g. Times),
'sans-serif' (e.g. Helvetica), 'cursive' (e.g. Zapf-Chancery),
'fantasy' (e.g. Western), and 'monospace' (e.g. Courier). Each of
these font families has a default list of font names in decreasing
order of priority associated with them. You describe which family you
want by choosing, eg, \code{family='serif'}, and the font manager will
search the font.serif list looking for one of the named fonts on your
system. The lists are user configurable, and reside in your
\fname{.matplotlibrc}.
This allows you to choose your family in your matplotlib script and
the font manager will try and find the best font no matter which
platform you run on.
\begin{itemize}
\item The \rc{font.style} property has three values: normal (or
roman), italic or oblique. The oblique style will be used for
italic, if it is not present.
\item The \rc{font.variant} property has two values: normal or
small-caps. For TrueType fonts, which are scalable fonts,
small-caps is equivalent to
using a font size of 'smaller', or about 83% of the current font size.
\item The \rc{font.weight} property has effectively 13 values: normal,
bold, bolder, lighter, 100, 200, 300, ..., 900. Normal is the same
as 400, and bold is 700. bolder and lighter are relative values
with respect to the current weight.
\item The \rc{font.stretch} property has 11 values: ultra-condensed,
extra-condensed, condensed, semi-condensed, normal, semi-expanded,
expanded, extra-expanded, ultra-expanded, wider, and narrower. This
property is not currently implemented.
\item The \rc{font.size} property has 11 values: xx-small, x-small,
small, medium, large, x-large, xx-large, larger, smaller, length
(such as 12pt), and percentage. larger and smaller are relative
values. percentage is not yet implemented.
\end{itemize}
Here is an example using the font properties to illustrate the
different fonts
\lstinputlisting{code/fonts_demo_kw.py}
% TODO: fix me for PS
%\fig{6in}{figures/fonts_demo_kw}{The various fonts rendered by the
% script above}{fig:fonts_demo}
\chapter{Collections}
\label{cha:collections}
\chapter{Tick locators and formatters}
\label{cha:tickers}
The \mpldoc{matplotlib.ticker} module contains classes to support
completely configurable tick locating and formatting. Although the
locators know nothing about major or minor ticks, they are used by the
Axis class to support major and minor tick locating and formatting.
Generic tick locators and formatters are provided, as well as domain
specific custom locators an formatters.
\section{Tick locating}
\label{sec:ticklocs}
Choosing tick locations and formats is a difficult and essential part
of making nice looking graphs. The \mpldoc{matplotlib.ticker} module
divides the workload between two bases classes: the locators and the
formatters. Each axis (eg the xaxis and yaxis) has a major and minor
tick locator and a major and minor tick formatter. The default minor
tick locators always return the empty list, ie, there are no minor
ticks. Each of these can be set independently, and it is easy for the
user to create and plug-in a custom tick locator or formatter.
The \mpldoc{matplotlib.ticker.Locator} class is the base class for all
tick locators. The locators handle autoscaling of the view limits
based on the data limits, and choosing the tick locations. The most
generally useful tick locator is \mpldoc{MultipleLocator}. You
initialize this with a base, eg 10, and it picks axis limits and ticks
that are multiples of your base. The class \mpldoc{AutoLocator}
contains a \mpldoc{MultipleLocator} instance, and dynamically updates
it based upon the data and zoom limits. This should provide much more
intelligent automatic tick locations both in figure creation and in
navigation than in prior versions of matplotlib. See
Tables~\ref{tab:locators} and \ref{tab:date_locators} for a summary of
the basic and date tick locators.
\begin{table}[htbp]
\centering
\begin{tabular}[t]{|l|l|}\hline
\carg{Class} & \val{Summary}\\\hline
NullLocator & No ticks\\
IndexLocator & locator for index plots (eg where \code{x = range(len(y))}\\
LinearLocator & evenly spaced ticks from min to max\\
LogLocator & logarithmically ticks from min to max\\
MultipleLocator & ticks and range are a multiple of base;
either integer or float \\
AutoLocator & choose a MultipleLocator and dynamically reassign\\\hline
\end{tabular}
\caption{\label{tab:locators}The basic tick locators}
\end{table}
\begin{table}[htbp]
\centering
\begin{tabular}[t]{|l|l|}\hline
\carg{Class} & \val{Summary}\\\hline
MinuteLocator & locate minutes that are a multiple of base\\
HourLocator & locate hours that are a multiple of base\\
DayLocator & locate a given hour each day\\
DayMultiLocator & ticks on day which are multiples of base\\
WeekdayLocator & locate a given weekday each week\\
WeekMultiLocator & ticks on weeks which are multiples of base\\
MonthLocator & locate months that are multiples of base\\
YearLocator & locate years that are multiples of base\\\hline
\end{tabular}
\caption{\label{tab:date_locators}The tick locators specialized for date plots}
\end{table}
You can define your own locator by deriving from Locator. You must
override the \code{\_\_call\_\_} method, which returns a sequence of
locations, and you will probably want to override the autoscale method
to set the view limits from the data limits. If you want to override
the default locator, use one of the above or a custom locator and pass
it to the x or y axis instance. The relevant methods are
\begin{lstlisting}
ax.xaxis.set_major_locator( xmajorLocator )
ax.xaxis.set_minor_locator( xminorLocator )
ax.yaxis.set_major_locator( ymajorLocator )
ax.yaxis.set_minor_locator( yminorLocator )
\end{lstlisting}
\noindent The default minor locator is the NullLocator, eg no minor ticks on by
default.
\section{Tick formatting}
Tick formatting is the process of converting the numeric tick location
into a suitable string, and is controlled by classes derived from
\mpldoc{matplotlib.ticker.Formatter}. The formatter operates on a
single tick value (and its tick position) and returns a string to the
axis. The tick formatters are summarized in
Table~\ref{tab:formatters}.
\begin{table}[htbp]
\centering
\begin{tabular}[t]{|l|l|}\hline
\carg{Class} & \val{Summary}\\\hline
NullFormatter & no labels on the ticks\\
FixedFormatter & set the strings manually for the labels\\
FuncFormatter & user defined function sets the labels\\
FormatStrFormatter & use a sprintf format string\\
IndexFormatter & cycle through fixed strings by tick position\\
ScalarFormatter & default formatter for scalars; autopick the fmt string\\
LogFormatter & formatter for log axes\\
DateFormatter & use an strftime string to format the date\\\hline
\end{tabular}
\caption{\label{tab:formatters}The tick formatting classes}
\end{table}
You can derive your own formatter from the Formatter base class by
simply overriding the \_\_call\_\_ method. The formatter class has
access to the axis view and data limits.
To control the major and minor tick label formats, use one of the
following methods::
\begin{lstlisting}
ax.xaxis.set_major_formatter( xmajorFormatter )
ax.xaxis.set_minor_formatter( xminorFormatter )
ax.yaxis.set_major_formatter( ymajorFormatter )
ax.yaxis.set_minor_formatter( yminorFormatter )
\end{lstlisting}
\section{Example 1: major and minor ticks}
In this example, the xaxis has major ticks that are multiples of 20
and minor ticks that are multiples of 5. The ticks are formatted with
an integer format string formatter '\%d'. The minor ticks are
unlabelled (\code{NullFormatter}).
The \code{MultipleLocator} ticker class is used to place ticks on
multiples of some base. The \code{FormatStrFormatter} uses a string format
string (eg'\%d' or '\%1.2f' or '\%1.1f cm' ) to format the tick.
Note that the matlab interface grid command changes the grid settings
of the major ticks of the y and y axis together. If you want to
control the grid of the minor ticks for a given axis, use for example
\code{ax.xaxis.grid(True, which='minor')}. See
Figure~\ref{fig:major_minor_demo}.
\fig{4in}{figures/major_minor_demo}{Creating custom major and minor
tick locators and formatters}{fig:major_minor_demo}
\lstinputlisting{code/major_minor_demo.py}
\section{Example 2: date ticking}
Making nice date/time plots requires custom tick locating and
formatting. matplotlib converts all datetimes to seconds since the
epoch, and supports a number of datetime converters to provide a
unified interface to popular datetime modules like python's datetime
module and the mx datetime module.
The example below uses the \mpldoc{matplotlib.finance} module to get
some historical quotes from yahoo's historical quotes server. The
datetime start and end points are specified using a python's datetime
module, so a PyDatetimeConverter is used to convert those into epoch
data. Major ticks are on the months (\code{MonthLocator}) and minor
ticks are on Mondays (\code{WeekdayLocator}). Only the major ticks
are labelled, using a strftime format string (\code{DateFormatter}).
Finally since the y axis is a stock price, a string formatter
(\code{FormatStrFormatter}) is used to place dollar signs on the y
tick labels.
\fig{4in}{figures/date_ticker_demo}{Providing custom tick locators and
formatters for financial/date plots}{fig:date_ticker_demo}
\lstinputlisting{code/date_ticker_demo.py}
\chapter{Cookbook}
\label{cha:cookbook}
\section{Data analysis}
\subsection{Linear regression}
\label{cbook:linear_regression}
One of the most common tasks in analyzing data is a linear regression
of one variable on another. matplotlib provides \func{polyfit} in the
\mpldoc{matplotlib.mlab} module for general polynomial regression.
\fig{4in}{figures/linear_regression}{Estimating a best fit line for
some random data}{fig:linear_regression}
\lstinputlisting{code/linear_regression.py}
\subsection{Polynomial regression}
\label{cbook:polynomial_regression}
polyfit can also be used for general polynomial fitting. The
signature of polyfit is \code{coeffs = polyfit(x, y, N)} where $N$ is
the order of the polynomial. The best fit can be obtained from the
coefficients and the x data using \code{best = polyval(x, coeefs)}.
\code{coeffs} are the coefficients of the polynomial $coeffs = p_k,
\dots, p_1, p_0$.
\fig{4in}{figures/poly_regression}{Estimating a best fit cubic for
some random data}{fig:poly_regression}
The algorithm for polyfit is taken from Mathworld's \textit{Least
Squares Fitting Polynomial} and \textit{Vandermonde Matrix} entries
\footnote{\url{http://mathworld.wolfram.com/LeastSquaresFittingPolynomial.html}}.
To do a best fit polynomial regression of order $N$ of $y$ onto $x$.
We must solve an $N$-dimensional system of equations; eg, for $N=2$
\begin{eqnarray}
\label{eq:polysys}
p_2*x_0^2 + p_1*x_0 + p_0 &=& y_1\nonumber\\
p_2*x_1^2 + p_1*x_1 + p_0 &=& y_1\nonumber\\
p_2*x_2^2 + p_1*x_2 + p_0 &=& y_2\nonumber\\
\dots & \nonumber\\
p_2*x_k^2 + p_1*x_k + p_0 &=& y_k\nonumber
\end{eqnarray}
\noindent If $X$ is a the Vandermonde Matrix computed from $x$, then the
polynomial least squares solution is given by the $p$ in $X*p = y$
where $X$ is a $x$ by $N+1$ matrix, $p$ is a $N+1$ length vector, and
$y$ is a len($x$) by 1 vector. This equation can be solved as
\begin{equation}
p = (\bar{X} X)^{-1} * \bar{X} * y
\end{equation}
\noindent where $\bar{X}$ is the transpose of X and the -1 superscript
denotes the inverse. For more info, see Mathworld, but note that the
$k$'s and $n$'s in the superscripts and subscripts on that page are
problematic. The linear algebra is correct, however.
\lstinputlisting{code/poly_regression.py}
\section{Working with images}
\subsection{Loading existing images into matplotlib}
\label{cbook:image_files}
Currently matplotlib only supports plotting images from numerix
arrays, either luminance, RGB or RGBA. If you have some existing data
in an image file format such as PNG, JPEG or TIFF, you can load this
into matplotlib by first loading the file into PIL -
\url{http://www.pythonware.com/products/pil} and then converting this
to a numerix array using fromstring / tostring methods
\lstinputlisting{code/from_pil.py}
\subsection{Blending several axes images using alpha}
\label{cbook:layer_images}
You can compose several axes images on top of one another using alpha
blending, as described in Section~\ref{sec:image_axes}. If your
\func{hold} state is \val{True}, multiple calls to
\func{imshow} will cause the image arrays to be resampled to the
axes bounding box and blended. Of course, the uppermost images must
have alpha less than one, or else they will be fully opaque and hence
the lower images will be invisible. Note that you can blend images
from arrays of different shapes as well as blending images with
different colormaps and interpolation schemes. The example below
creates a black and white checkboard using a grayscale colormap and
then blends a color image over it, as shown in
Figure~\ref{fig:layer_images}.
\fig{4in}{figures/layer_images}{Layering axes images using alpha blending.}
{fig:layer_images}
\lstinputlisting{code/layer_images.py}
\subsection{Creating a mosaic of images}
\label{cbook:figure_mosaic}
You can compose several figure images into a mosaic using the
\func{figimage} command, as discussed Section~\ref{sec:image_figure}. If
your \func{hold} state is \val{True}, multiple calls to
\code{figimage(X, xo, yo)}. xo and yo are the pixel offsets from
the origin (the origin can be either upper left or lower left, as
discussed in Section~\ref{sec:image_origin}). The code below using color
mapping to place two images on the diagonal. Note that you can use
different kinds of arrays (luminance, RGB, RGBA) and different
colormaps when creating figure mosaics. See
Figure~\ref{fig:figure_mosaic}.
\fig{4in}{figures/figure_mosaic}{Creating a mosaic using \func{figimage}}
{fig:figure_mosaic}
\lstinputlisting{code/figure_mosaic.py}
\subsection{Defining your own colormap}
Perry Greenfield has provided a nice framework with
\mpldoc{matplotlib.colors.LinearSegmentedColormap} to define new
colormaps. You can create new colormaps fairly easy by following the
example of jet in \mpldoc{matplotlib.cm}. Here are the steps
\begin{itemize}
\item define your rgb linear segments in \mpldoc{matplotlib.cm},
following the lead of the \val{\_jet\_data} dictionary in that module
\item add an entry to the datad dictionary in that module which maps
rc string names for your color map to the dictionary you just
defined.
\item instantiate a single instance of your colormap in cm, following
the example
\begin{lstlisting}
jet = colors.LinearSegmentedColormap('jet', _jet_data, LUTSIZE)
\end{lstlisting}
\item{add a matplotlib.matlab function which has the same name as your
colormap, following the example of \mpldoc{matplotlib.matlab.jet}.}
\end{itemize}
\noindent Now anyone can use the colormap interactively from the shell, by
setting it as the default image.cmap in rc, etc. Please submit your
changes to the matplotlib-devel mailing list.
\appendix
\chapter{A sample \fname{.matplotlibrc}}
\label{cha:rc}
\lstinputlisting{../.matplotlibrc}
\chapter{mathtext symbols}
\label{cha:math_symbols}
\end{document}
