`_ to get a better picture.
.. admonition:: Clearing the figure with plt.clf()
From now on we will assume that you know to clear the figure with
`clf()`_ before entering commands to make the next plot.
For every x, y pair of arguments, there is an optional third argument
which is the format string that indicates the color and line type of
the plot. The letters and symbols of the format string are from
MATLAB, and you concatenate a color string with a line style string.
The default format string is 'b-', which is a solid blue line. For
example, to plot the above with red circles, you would issue::
plt.clf()
plt.plot([1,2,3,4], [1,4,9,16], 'ro')
plt.axis([0, 6, 0, 20])
.. image:: pyplot_formatstr.png
See the `plot()`_ documentation for a complete
list of line styles and format strings. The
`axis()`_ command in the example above takes a
list of ``[xmin, xmax, ymin, ymax]`` and specifies the viewport of the
axes.
If matplotlib were limited to working with lists, it would be fairly
useless for numeric processing. Generally, you will use `NumPy`_
arrays. In fact, all sequences are
converted to numpy arrays internally. The example below illustrates a
plotting several lines with different format styles in one command
using arrays::
# evenly sampled time at 200ms intervals
t = np.arange(0., 5., 0.2)
# red dashes, blue squares and green triangles
# then filled circle with connecting line
plt.clf()
plt.plot(t, t, 'r--', t, t**2, 'bs', t, t**3, 'g^')
plt.plot(t, t+60, 'o', linestyle='-', color='c')
.. image:: pyplot_three_v2.png
:scale: 70
.. admonition:: Exercise: Make this plot
.. image:: big_hexes.png
:scale: 50
Use the `plot()`_ documentation to make a plot that looks similar to the one
above. Start with::
x = [1, 2, 3, 4]
y = [3, 2, 3, 1]
.. raw:: html
Click to Show/Hide Solution
::
x = [1, 2, 3, 4]
y = [3, 2, 3, 1]
plt.clf()
plt.plot(x, y, '-.', linewidth=10)
plt.plot(x, y, 'H', markeredgecolor='b', markeredgewidth=10, markerfacecolor='r', markersize=40)
plt.axis([0, 5, 0, 4])
.. raw:: html
What are all these icons for?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The figures are enclosed in a window that looks a little like the
following
(it depends on the OS and matplotlib backend being used):
.. image:: pyplot_window.png
The icons at the bottom of the window allow you to zoom in or out of
the plot, pan around, and save the plot as a "hardcopy" format (e.g.
PNG, postscript, or PDF).
The first icon will reset you to the original axis limits, which comes
in quite handy.
You *can* use the close button to close the window, but it is best to
use the `close()`_ command to avoid memory leaks.
Saving the plot
^^^^^^^^^^^^^^^
As discussed above, you can use the GUI to save the plot, but the
`savefig()`_ command is often more useful, and has many options::
plt.savefig('fig.png')
plt.savefig('fig.pdf')
Note that you can save a figure multiple times (e.g. as different
formats). The supported formats depend on the backend being used, but
normally include png, pdf, ps, eps and svg::
plt.savefig('fig') # creates fig.png (unless you have changed the default format)
plt.savefig('fig.pdf') # creates a PDF file, fig.pdf
plt.savefig('fig', format='svg') # creates a SVG file called fig
plt.savefig('fig.svg', 'format='ps') # creates a PS file called fig.svg (do not do this!)
The default format (used in the first line) can be queried, or
changed, by saying::
>>> rcParams['savefig.format']
'png'
>>> rcParams['savefig.format'] = 'pdf'
>>> plt.savefig('foo') # creates foo.pdf
Some common-ish Python errors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here's a couple of errors you may come across::
>>> plt.clf
>>> x = np.arange(5)
>>> x.size()
TypeError: 'int' object is not callable
Since ``clf`` is a function then you need to add ``()`` to actually
call it (being able to refer to a function as a "thing" is incredibly
powerful, which is what has happened here, but it's not much use
if you just want to clear the current figure).
For the second case, ``x.size`` returns an integer (in this case
``5``), which we then call as a function, leading to the
somewhat cryptic messsage above. For new users it would be nice if it
said "hold on, size isn't callable", but then this would inhibit
useful - if complex - statements such as::
tarfile.open(fileobj=request.urlopen(url), mode='r|').extractall()
Controlling line properties
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. admonition:: What are lines and markers?
A matplotlib "line" is a object containing a set of points and various
attributes describing how to draw those points. The points are optionally
drawn with "markers" and the connections between points can be drawn with
various styles of line (including no connecting line at all).
Lines have many attributes that you can set: linewidth, dash style,
antialiased, etc; see `Line2D`_. There are several ways to set line
properties
* Use keyword args::
x = np.arange(0, 10, 0.25)
y = np.sin(x)
plt.clf()
plt.plot(x, y, linewidth=4.0)
* Use the `setp()`_ command. The example below
uses a MATLAB-style command to set multiple properties
on a list of lines. ``setp`` works transparently with a list of objects
or a single object::
plt.clf()
lines = plt.plot(x, y, 'r', x/2, y/2, 'b')
plt.setp(lines, color='r', linewidth=4.0)
* Use the setter methods of the ``Line2D`` instance. ``plot`` returns a list
of lines; eg ``line1, line2 = plot(x1,y1,x2,x2)``. Below I have only
one line so it is a list of length 1. I use tuple unpacking in the
``line, = plot(x, y, 'o')`` to get the first element of the list::
plt.clf()
line, = plt.plot(x, y, '-')
line.set_
Now change the line color, noting that in this case you need to explicitly redraw::
line.set_color('m') # change color
plt.draw()
.. Important::
In contrast to old-school plotting where you issue a plot command and
the line is immortalized, in matplotlib the lines (and basically everything
about the plot) are *dynamic objects* that can be modified after the fact.
Here are the available `Line2D`_ properties.
====================== ==================================================
Property Value Type
====================== ==================================================
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
clip_path a Path instance and a Transform instance, a Patch
color or c any matplotlib color
contains the hit testing function
dash_capstyle ['butt' | 'round' | 'projecting']
dash_joinstyle ['miter' | 'round' | 'bevel']
dashes sequence of on/off ink in points
data (array xdata, array ydata)
figure a matplotlib.figure.Figure instance
label any string
linestyle or ls [ '-' | '--' | '-.' | ':' | 'steps' | ...]
linewidth or lw float value in points
lod [True | False]
marker [ '+' | ',' | '.' | '1' | '2' | '3' | '4' | ... ]
markeredgecolor or mec any matplotlib color
markeredgewidth or mew float value in points
markerfacecolor or mfc any matplotlib color
markersize or ms float
markevery None | integer | (startind, stride)
picker used in interactive line selection
pickradius the line pick selection radius
solid_capstyle ['butt' | 'round' | 'projecting']
solid_joinstyle ['miter' | 'round' | 'bevel']
transform a matplotlib.transforms.Transform instance
visible [True | False]
xdata array
ydata array
zorder any number
====================== ==================================================
To get a list of settable line properties, call the
`setp()`_ function with a line or lines
as argument::
lines = plt.plot([1,2,3])
plt.setp(lines)
.. _multiple-figs-axes:
.. admonition:: Detour into Python
You may have noticed that in the last workshop we mostly used NumPy arrays like
``np.arange(5)`` or ``np.array([1,2,3,4])`` but now you are seeing statements like
``plt.plot([1,2,3])``.
.. _controlling-line-properties:
Some useful functions for controlling plotting
----------------------------------------------
Here are a few useful functions:
======================== ========================================================================================
`figure()`_ Make new figure frame (accepts figsize=(width,height) in inches)
`autoscale()`_ Allow or disable autoscaling and control space beyond data limits
`hold()`_ Hold figure: hold(False) means next plot() command wipes figure
`ion()`_, `ioff()`_ Turn interactive plotting on and off
`axis()`_ Set plot axis limits or set aspect ratio (plus more)
`subplots_adjust()`_ Adjust the spacing around subplots (fix clipped labels etc)
`xlim()`_, `ylim()`_ Set x and y axis limits individually
`xticks()`_, `yticks()`_ Set x and y axis ticks
======================== ========================================================================================
Working with multiple figures and axes
----------------------------------------
MATLAB, and `matplotlib.pyplot`_, have the concept of the current
figure and the current axes. All plotting commands apply to the
current axes. The function `gca()`_ returns the
current axes (an `Axes`_ instance), and
`gcf()`_ returns the current figure
(a `Figure`_ instance). Normally, you don't have
to worry about this, because it is all taken care of behind the
scenes.
.. admonition:: Figure, Axes, plot(), and subplot()
`Figure`_
This is the entire window where one or more subplots live.
A Figure object (new window) is created with the `figure()`_ command.
`Axes`_
This is an object representing a subplot (which you might casually
call a "plot") which contains axes, ticks, lines, points, text, etc.
`plot()`_
This is a command that draws points or lines and returns a list of
`Line2D`_ objects. One sublety is that `plot()`_ will automatically
call `figure()`_ and/or `subplot()`_ if neccesary to create the
underlying `Figure`_ and `Axes`_ objects.
`subplot()`_
This is a command that creates and returns a new subplot (`Axes`_) object
which will be used for subsequent plotting commands.
Below is a script that illustrates this by creating two figures where the first
figure has two subplots::
def f(t):
"""Python function to calculate a decaying sinusoid"""
val = np.exp(-t) * np.cos(2*np.pi*t)
return val
t1 = np.arange(0.0, 5.0, 0.1)
t2 = np.arange(0.0, 5.0, 0.02)
plt.figure(1) # Make the first figure
plt.clf()
plt.subplot(2, 1, 1) # 2 rows, 1 column, plot 1
plt.plot(t1, f(t1), 'bo', t2, f(t2), 'k')
plt.title('FIGURE 1')
plt.text(2, 0.8, 'AXES 211')
plt.subplot(2, 1, 2) # 2 rows, 1 column, plot 2
plt.plot(t2, np.cos(2*np.pi*t2), 'r--')
plt.text(2, 0.8, 'AXES 212')
plt.figure(2) # Make a second figure
plt.clf()
plt.plot(t2, f(t2), '*')
plt.grid()
plt.title('FIGURE 2')
plt.text(2, 0.8, 'AXES 111')
+--------------------------+---------------------------+
|.. image:: mult_figs1.png |.. image:: mult_figs2.png |
| :scale: 50 % | :scale: 50 % |
+--------------------------+---------------------------+
The first `figure()`_ command here is optional because
``figure(1)`` will be created by default, just as a ``subplot(1, 1, 1)``
will be created by default if you don't manually specify an axes.
The `subplot()`_ command specifies ``numrows, numcols, fignum`` where
``fignum`` ranges from 1 to ``numrows*numcols``. The commas in the ``subplot``
command are optional if ``numrows*numcols<10`` so you might see calls like
``subplot(211)`` in code, but don't do this yourself. You can create an
arbitrary number of subplots and axes.
If you want to place an axes manually, ie, not on a rectangular grid, use the
`axes()`_ command, which allows you to specify the location as ``axes([left,
bottom, width, height])`` where all values are in fractional (0 to 1)
coordinates. See `pylab_examples-axes_demo
`_
for an example of placing axes manually and `pylab_examples-line_styles
`_
for an example with lots-o-subplots.
You can move back to existing subplots, or indeed figures, as shown below::
plt.figure(1) # Select the existing first figure
plt.subplot(2, 1, 2) # Select the existing subplot 212
plt.plot(t2, np.cos(np.pi*t2), 'g--') # Add a plot to the axes
plt.text(0.2, -0.8, 'Back to AXES 212', color='g', size=18) # add a colored label, increasing the font size
You can clear the current figure with `clf()`_ and the current axes with
`cla()`_. If you find this statefulness, annoying, don't despair, this is just
a thin stateful wrapper around an object oriented API, which you can use
instead. See the :ref:`advanced_plotting` page for an introduction to this
approach, and the then `Artist tutorial
`_ for the gory details.
Figures can be deleted with the `close()`_ command::
plt.close(2) # Remove the second figure
.. admonition:: Using close
You can use the 'close button' provided by the window manager
to remove the figure, but if you do this you must *still* call
the `close()`_ command, to ensure that memory allocated by pyplot
for the figure is released. This is only really an issue for
long-running ``ipython`` sessions; if you just create a single
plot and then exit you do not need to use ``close``.
.. _working-with-text:
Working with text
-------------------
The `text()`_ command can be used to add text in
an arbitrary location, and the `xlabel()`_,
`ylabel()`_ and `title()`_
are used to add text in the indicated locations (see `Text intro`_
for a more detailed example)::
mu, sigma = 100, 15
x = np.random.normal(mu, sigma, size=10000)
plt.clf()
# the histogram of the data
histvals, binvals, patches = plt.hist(x, bins=50, normed=True, facecolor='g', alpha=0.75)
plt.xlabel('Smarts')
plt.ylabel('Probability')
plt.title('Histogram of IQ')
plt.text(60, .025, r'$\mu=100,\ \sigma=15$')
plt.axis([40, 160, 0, 0.03])
plt.grid(True)
.. image:: pyplot_text.png
All of the `text()`_ commands return an
:class:`matplotlib.text.Text` instance. Just as with with lines
above, you can customize the properties by passing keyword arguments
into the text functions or using `setp()`_::
t = plt.xlabel('my data', fontsize=14, color='red')
These properties are covered in more detail in `text-properties `_.
.. admonition:: Exercise: Overlaying histograms
Make an additional normal distribution with a mean of 130. Make a new plot
where the two distributions are overlayed. Use a different color and
choose the opacities so it looks reasonable.
Hint:
- You might want to use the ``bin`` parameter with an ``arange(min, max,
step)`` so both histograms are binned the same.
.. raw:: html
Click to Show/Hide Solution
::
plt.clf()
x2 = np.random.normal(130, sigma, size=10000)
out = plt.hist(x, bins=50, facecolor='g', alpha=0.5)
out2 = plt.hist(x2, bins=50, facecolor='r', alpha=0.5)
.. raw:: html
Getting the fonts just right
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The global font properties for various plot elements can be controlled using
the `rc()`_ function::
plt.rc("font", size=10, family='normal', weight='bold')
plt.rc("axes", labelsize=10, titlesize=10)
plt.rc("xtick", labelsize=10)
plt.rc("ytick", labelsize=10)
plt.rc("legend", fontsize=10)
The inconsistency here is one of the warts in matplotlib. Ironically my favorite
way to find these valuable commands is to google `"matplotlib makes me
hate"
`_
which brings up a blog post ranting about the problems with matplotlib.
All of the attributes that can be controlled with the `rc()`_ command are
listed in ``$HOME/.matplotlib/matplotlibrc`` and `Customizing matplotlib
`_.
See also the :ref:`advanced_plotting` page.
Using mathematical expressions in text
----------------------------------------
matplotlib accepts TeX equation expressions in any text expression.
For example to write the expression :math:`\sigma_i=15` in the title,
you can write a TeX expression surrounded by dollar signs::
plt.title(r'$\sigma_i=15$')
The ``r`` preceeding the title string is important -- it signifies that the
string is a *raw* string and not to treate backslashes as python escapes.
matplotlib has a built-in TeX expression parser and layout engine, and ships
its own math fonts -- for details see the `mathtext-tutorial
`_. Thus you can use
mathematical text across platforms without requiring a TeX installation. For
those who have LaTeX and dvipng installed, you can also use LaTeX to format
your text and incorporate the output directly into your display figures or
saved postscript -- see the `usetex-tutorial
`_.
Annotating text
-----------------
The uses of the basic `text()`_ command above
place text at an arbitrary position on the Axes. A common use case of
text is to annotate some feature of the plot, and the
`annotate()`_ method provides helper
functionality to make annotations easy. In an annotation, there are
two points to consider: the location being annotated represented by
the argument ``xy`` and the location of the text ``xytext``. Both of
these arguments are ``(x,y)`` tuples::
plt.clf()
t = np.arange(0.0, 5.0, 0.01)
s = np.cos(2*pi*t)
lines = plt.plot(t, s, lw=2)
plt.annotate('local max', xy=(2, 1), xytext=(3, 1.5),
arrowprops=dict(facecolor='black', shrink=0.05))
plt.ylim(-2,2)
.. image:: pyplot_annotate.png
In this basic example, both the ``xy`` (arrow tip) and ``xytext``
locations (text location) are in data coordinates. There are a
variety of other coordinate systems one can choose -- see the
`Annotations introduction `_
for more details and links to examples.
Plotting 2-d data
------------------------
A deeper tutorial on plotting 2-d image data will have to wait for another
day:
- For simple cases it is straightforward and everything you need
to know is in the `image tutorial
`_
- For making publication quality images for astronomy you should be
using `APLpy`_.
Plotting 3-d data
-------------------
Matplotlib supports plotting 3-d data through the ``mpl_toolkits.mplot3d``
module. This is a somewhat specialized functionality but it's worth quickly
looking at an example of the 3-d viewer that is available::
from mpl_toolkits.mplot3d import Axes3D
def randrange(n, vmin, vmax):
return (vmax-vmin)*np.random.rand(n) + vmin
fig = plt.figure()
ax = fig.add_subplot(111, projection='3d')
n = 100
for c, m, zl, zh in [('r', 'o', -50, -25), ('b', '^', -30, -5)]:
xs = randrange(n, 23, 32)
ys = randrange(n, 0, 100)
zs = randrange(n, zl, zh)
ax.scatter(xs, ys, zs, c=c, marker=m)
ax.set_xlabel('X Label')
ax.set_ylabel('Y Label')
ax.set_zlabel('Z Label')
.. image:: pyplot_3d.png
To get more information check out the `mplot3d tutorial
`_.
Appendix: Pylab and Pyplot and NumPy
-------------------------------------
You may see examples that use the ``pylab`` mode of IPython by using
``ipython --pylab`` or the ``%pylab`` magic function.
Let's demystify what's happening in this case and
clarify the relationship between **pylab** and **pyplot**.
`matplotlib.pyplot`_ is a collection of command style functions that make
matplotlib work like MATLAB. This is just a package module that you can import::
import matplotlib.pyplot
print(sorted(dir(matplotlib.pyplot)))
Likewise pylab is also a module provided by matplotlib that you can import::
import pylab
This module is a thin wrapper around ``matplotlib.pylab`` which pulls in:
- Everything in ``matplotlib.pyplot``
- All top-level functions ``numpy``, ``numpy.fft``, ``numpy.random``,
``numpy.linalg``
- A selection of other useful functions and modules from matplotlib
There is no magic, and to see for yourself do
.. sourcecode:: python
import matplotlib.pylab
matplotlib.pylab?? # prints the source code!!
When you do ``ipython --pylab`` it (essentially) just does::
from pylab import *
There is one technical detail about GUI event loops and plot window interaction
which makes it useful to use ``--pylab`` even if you are not directly using all the
top-level functions like ``plot()`` that get imported.
In a lot of documentation examples you will see code like::
import matplotlib.pyplot as plt # set plt as alias for matplotlib.pyplot
plt.plot([1,2], [3,4])
Now you should understand this is the same ``plot()`` function that you get in
Pylab.
See `Matplotlib, pylab, and pyplot: how are they related?
`_
for a more discussion on the topic.