Upload
clementine-strickland
View
225
Download
0
Tags:
Embed Size (px)
Citation preview
Documentation Homepage
http://matplotlib.sourceforge.net/ Short descriptions of and links to documentation on all plotting functions
PyplotTutorial (8 pp.)
http://matplotlib.sourceforge.net/users/pyplot_tutorial.html Start here Pyplot is a collection of command style functions that make matplotlib work
like matlab User’s Guide
http://matplotlib.sourceforge.net/users_guide_0.98.3.pdf Refer to as needed
Cookbook / Matplotlib http://www.scipy.org/Cookbook/Matplotlib Lots of good examples Shows figure, link to page giving code and explanation
Examples
http://matplotlib.sourceforge.net/examples/
Just a directory listing, but subdirectory names are descriptive
The “What's new” page
http://matplotlib.sourceforge.net/users/whats_new.html
Every feature ever introduced into matplotlib is listed here under the version that introduced it
Often with a link to an example or documentation
Global Module Index
http://matplotlib.sourceforge.net/modindex.html Documentation on the various modules
This and the next are often the only places to find something
The Matplotlib API
http://matplotlib.sourceforge.net/api/
Documentation on the various packages
Matplotlib Backends See http://matplotlib.sourceforge.net/api/index_backend_api.html Matplotlib uses a backend to produce device-independent output (e.g., pdf,
ps, png)
For backends without a GUI, only output is an explicitly-saved image file
File
…\site-packages\matplotlib\mpl-data\matplotlibrc
sets the default backend with a line for the backend option
The Windows distribution has
backend : TkAgg Specifies the agg backend (for rendering) for Tkinter Tkinter is a Python binding to the Tk GUI toolkit
Still the most popular Python GUI toolkit Other toolkits: wxPython
Tk is an open source, cross-platform widget toolkit—library of basic elements for building a GUI
The antigrain geometry (Agg) library is a platform independent library
Provides efficient antialiased rendering with a vector model
Doesn't depend on a GUI framework Used in web application servers and for generating images in
batch scripts
Matplotlib includes its own copy of Agg
Aliasing is an effect that causes different continuous signals to become indistinguishable (aliases of one another) when sampled Also refers to the resulting distortion Anti-aliasing is the technique of minimizing this distortion
Used in digital photography, computer graphics, digital audio, etc.
matplotlib.pyplot vs. pylab Package matplotlib.pyplot provides a MATLAB-like plotting
framework
Package pylab combines pyplot with NumPy into a single namespace
Convenient for interactive work
For programming, it’s recommended that the namespaces be kept separate
See such things as
import pylab
Or
import matplotlib.pyplot as plt The standard alias
import numpy as np
The standard alias
Also
from pylab import *
Or
from matplotlib.pyplot import *
from numpy import *
We’ll use
from pylab import *
Some examples don’t show this—just assume it
Batch and Interactive Use In a script,
import the names in the matplotlib namespace (pylab)
then list the commands
Example: file E:\SomeFolder\mpl1.py
from pylab import *
plot([1,2,3,4])
show()
Executing
E:\SomeFolder>mpl1.py
produces the figure shown
The command line hangs until the figure is dismissed (click ‘X’ in the upper right)
plot()
Given a single list or array, plot() assumes it’s a vector of y-values
Automatically generates an x vector of the same length with consecutive integers beginning with 0
Here [0,1,2,3]
To override default behavior, supply the x data: plot(x,y )
where x and y have equal lengths
show()
Should be called at most once per script
Last line of the script
Then the GUI takes control, rendering the figure
In place of show(), can save the figure to with, say,
savefig(‘fig1.png’)
Saved in the same folder as the script
Override this with a full pathname as argument—e.g.,
savefig('E:\\SomeOtherFolder\\fig1.png')
Supported formats: emf, eps, pdf, png, ps, raw, rgba, svg, svgz
If no extension specified, defaults to .png
With the TkAgg backend, can use matplotlib from an arbitrary python (interactive) shell
Supposedly requires the matplotlibrc file to have interactive set to True (as well as backend to TkAgg )
In the matplotlibrc file with the Windows distribution, the interactive setting (to False) is commented out
TkAgg sets interactive mode to True when show() or draw() executed
In batch mode (running scripts), interactive mode can be slow
Redraws the figure with each command.
Matplotlib from the Shell Using matplotlib in the shell, we see the objects produced
>>> from pylab import *
>>> plot([1,2,3,4])
[<matplotlib.lines.Line2D object at 0x01A3EF30>]
>>> show()
Hangs until the figure is dismissed or close() issued
show() clears the figure: issuing it again has no result
If you construct another figure, show() displays it without hanging
draw() Clear the current figure and display a blank figure without hanging
Results of subsequent commands added to the figure
>>> draw()
>>> plot([1,2,3])[<matplotlib.lines.Line2D object at 0x01C4B6B0>]
>>> plot([1,2,3],[0,1,2])[<matplotlib.lines.Line2D object at 0x01D28330>]
Shows 2 lines on the figure
Use close() to dismiss the figure and clear it
clf() clears the figure (also deletes the white background) without dismissing it
Figures saved using savefig() in the shell by default are saved in
C:\Python25 Override this by giving a full pathname
Interactive Mode In interactive mode, objects are displayed as soon as they’re created
Use ion() to turn on interactive mode, ioff() to turn it off
Example Import the pylab namespace, turn on interactive mode and plot a line
>>> from pylab import *
>>> ion()
>>> plot([1,2,3,4])
[<matplotlib.lines.Line2D object at 0x02694A10>]
A figure appears with this line on it
The command line doesn’t hang
Plot another line
>>> plot([4,3,2,1])
[<matplotlib.lines.Line2D object at 0x00D68C30>]
This line is shown on the figure as soon as the command is issued
Turn off interactive mode and plot another line
>>> ioff()
>>> plot([3,2.5,2,1.5])
[<matplotlib.lines.Line2D object at 0x00D09090>] The figure remains unchanged—no new line
Update the figure
>>> show()
The figure now has all 3 lines
The command line is hung until the figure is dismissed
Matplotlib in Ipython Recommended way to use matplotlib interactively is with ipython
In the Ipython drop-down menu, select pylab
Ipython’s pylab mode detects the matplotlibrc file
Makes the right settings to run matplotlib with your GUI of choice in interactive mode using threading
Ipython in pylab mode knows enough about matplotlib internals to make all the right settings
Plots items as they’re produce without draw() or show()
Default folder for saving figures on file
C:\Documents and Settings\current user
Toolbar In interactive mode, at the bottom left of the figure
Not included when a figure is written to file
From right to left
Save: Launches a file save dialog, initially at
C:\Documents and Settings\current user with .png as default
All *Agg backends know how to save image types: PNG, PS, EPS, SVG
Subplot configuration
Adjust the left, bottom, right, or top margin of the figure
With text, control spacing
The Zoom to rectangle:
Define a rectangle by pressing the left mouse button to define one vertex and dragging out to the opposite vertex and releasing
Content of the rectangle occupies the entire space for the figure
The Pan/Zoom: 2 modes
Pan Mode Press the left mouse button, drag it to a new position The figure is pulled along within the frame
Extended by blank area if needed
Zoom Mode Press the right mouse button, drag it to a new position Figure is stretched proportional to the distance dragged in the direction
dragged up and to the right. Shrunk proportional to the distance dragged down and to the left
Use modifier keys x, y or Ctrl to constrain the zoom to the x or y axis or to preserve the aspect ratio preserve, resp.
Forward and Back.
Navigate back and forth between previously defined views
Analogous to forward and back buttons of a web browser
Home
Return to the first (default) view
More Curve Plotting plot() has a format string argument specifying the color and line type
Goes after the y argument (whether or not there’s an x argument)
Can specify one or the other or concatenate a color string with a line style string in either order
Default format string is 'b-' ( solid blue line)
Some color abbreviations
b (blue), g (green), r (red), k (black), c (cyan)
Can specify colors in many other ways (e.g., RGB triples)
Some line styles that fill in the line between the specified points
- (solid line), -- (dashed line), -. (dash-dot line), : (dotted line)
Some line styles that don’t fill in the line between the specified point
o (circles), + (plus symbols), x (crosses), D (diamond symbols)
For a complete list of line styles and format strings,
http://matplotlib.sourceforge.net/api/pyplot_api.html#module-matplotlib.pyplot Look under matplotlib.pyplot.plot()
The axis() command takes a list
[xmin, xmax, ymin, ymax]
and specifies the view port of the axes
ExampleIn [1]: plot([1,2,3,4], [1,4,9,16], 'ro')
Out[1]: [<matplotlib.lines.Line2D object at 0x034579D0>]
In [2]: axis([0, 6, 0, 20])
Out[2]: [0, 6, 0, 20]
Other arguments for the axis() command
‘off’ turns off the axis lines and labels
‘equal’ changes the limits of the x and y axes so that equal increments of x and y have the same length
‘scaled’ achieves the same result as ‘equal’ by changing the dimensions of the plot box instead of the axis limit
‘tight’ changes the axis limits to show all the data and no more
‘image’ is scaled with the axis limits equal to the data limits
axis() with no argument returns the current axis limits,
[xmin, xmax, ymin, ymax]
Generally work with arrays, not lists All sequences are converted to NumPy arrays internally
plot() can draw more than one line at a time Put the (1-3) arguments for one line in the figure
Then the (1-3) arguments for the next line
And so on
Can’t have 2 lines in succession specified just by their y arguments
matplotlib couldn’t tell whether it’s a y then the next y or an x then the corresponding y
The example (next slide) illustrates plotting several lines with different format styles in one command using arrays
In [1]: t = arange(0.0, 5.2, 0.2)
In [2]: plot(t, t, t, t**2, 'rs', t, t**3, 'g^')
Out[2]:
[<matplotlib.lines.Line2D object at 0x02A6D410>,
<matplotlib.lines.Line2D object at 0x02A6D650>,
<matplotlib.lines.Line2D object at 0x02A6D8D0>]
If the y for plot() is 2-dimensional, then the columns are plotted—e.g.,
In [1]: a = linspace(0, 2*pi, 13)
In [2]: b_temp = array([sin(a), cos(a)])
In [3]: b = b_temp.transpose()
In [4]: plot(a, b)
Out[4]:
[<matplotlib.lines.Line2D object at 0x02A770D0>,
<matplotlib.lines.Line2D object at 0x02A77150>]
Controlling Line Properties Lines you encounter are instances of the Line2D class
Instances have the following propertiesProperty Values
alpha The alpha transparency on 0-1 scale
antialiased True | False - use antialised rendering
color a matplotlib color arg
label a string optionally used for legend
linestyle One of -- : -. -
linewidth a float, the line width in points
marker One of + , o . s v x > < ^
markeredgewidth The line width around the marker symbol
markeredgecolor The edge color if a marker is used
markerfacecolor The face color if a marker is used
markersize The size of the marker in points
alpha = 0.0 is complete transparency, alpha = 1.0 is complete opacity
Markers Some of the line types in a format
string give continuous lines
A marker is a symbol displayed at only the specified points on a continuous line
In the format string, indicate a marker with a 3rd symbol One of +, o, s, v, x, >, <, ^
The 3 symbols can occur in any order No ambiguity: a marker can’t
be used with a non-continuous line type
In [50]: plot([0,1,2,3], 'g:o')
Out[50]: [<matplotlib.lines.Line2D object at 0x03017BB0>]
Three Ways to Set Line Properties One way: Use keyword line properties as keyword arguments—e.g.,
plot(x, y, linewidth=2.0)
Another way: Use the setter methods of the Line2D instance
For every property prop, there’s a set_prop() method that takes an update value for that property
To use this, note that plot() returns a list of lines—e.g.,
line1, line2 = plot(x1,y1,x2,x2)
The following example has 1 line with tuple unpacking
line, = plot(x, y, 'o')
line.set_antialiased(False)
The 3rd (and final) way to set line properties: use function setp()
1st argument can be an object or sequence of objects
The rest are keyword arguments updating the object’s (or objects’) properties
The following sets the color and linewidth properties of two lines
lines = plot(x1, y1, x2, y2)
setp(lines, color='r', linewidth=2.0)
setp() also accepts property-value pairs of arguments with property names as strings—e.g.,
setp(lines, 'color', 'r', 'linewidth', 2.0)
When setp() has just an object and a property name as arguments, it lists all possible values for that propertyIn [38]: setp(l1, 'linestyle')
linestyle: [ '-' | '--' | '-.' | ':' | 'steps' | 'steps-pre' | 'steps-mid' | 'steps-post' | 'None' | ' ' | '' ]
When setp() has an object as its sole argument, it lists the names of the properties of that object
Multiple Figures and Axes Pylab has the concepts of the current figure and the current axes
An instance of class Figure contains all the plot elements
An instance of class Axes contains most of the figure elements:
instances of Axis, Tick, Line2D, Text, Polygon, …
But 1 figure may have multiple instances of Axes (“graphs”)
All plot and text label commands apply to the current axes
Function gca() returns the current axes as an Axes instance
Function gcf() returns the current figure as a Figure instance
Normally, all is taken care of behind the scenes
Function figure() returns an instance of Figure
Can take a number of arguments
Most have reasonable defaults set in the matplotlibrc file
Typically called with 1 (the figure number) or none
Called with none, the figure number is incremented and a new, current figure returned The figure number starts at 1 A Figure instance has a number property
Called with an integer argument,
if there’s a figure with that number, it becomes the current figure
If not, a new figure with that number is created
Example using multiple figures
figure(1)
plot([1,2,3])
figure(2)
plot([4,5,6])
figure(1) # make figure 1 current
title('Easy as 1,2,3')
In ipython, this opens 2 figure windows
Now consider close() more generally
Takes 1 or no argument; if the argument is
None, closes the current figure
A number, closes the figure with that number
A Figure instance, closes that figure
‘all’, closes all figures
Text The text commands are self-explanatory
xlabel() ylabel() title() text()
In simple cases, all but text() take just a string argument
text() needs at least 3 arguments:
x and y coordinates (as per the axes) and a string
All take optional keyword arguments or dictionaries to specify the font properties
They return instances of class Text
The following font properties of Text instances can be set
Property Values
alpha The alpha transparency on 0-1 scale
color a matplotlib color argument
fontangle italic | normal | oblique
fontname Sans | Helvetica | Courier | Times | Others
fontsize a scalar, eg, 10
fontweight normal | bold | light 4
horizontalalignment left | center | right
rotation horizontal | vertical
verticalalignment bottom | center | top
Three ways to specify font properties: using setp object oriented methods font dictionaries
Controlling Text Properties with setp Use setp to set any property
t = xlabel('time')
setp(t, color='r', fontweight='bold')
Also works with a list of text instances E.g., to change the properties of all the tick labels
labels = getp(gca(), 'xticklabels')
setp(labels, color='r', fontweight='bold')
Controlling Text Using Object Methods setp is just a wrapper around the Text set methods
Can prepend set_ to the text property and make a normal instance method call
t = xlabel('time')
t.set_color('r')
t.set_fontweight('bold')
Controlling Text Using Keyword Arguments & Dictionaries
All text commands take an optional dictionary argument and keyword arguments to control font properties
E.g., to set a default font theme and override individual properties for given text commands
font = {'fontname' : 'Courier',
'color' : 'r',
'fontweight' : 'bold',
'fontsize' : 11}
plot([1,2,3])
title('A title', font, fontsize=12)
text(0.5, 2.5, 'a line', font, color='k')
xlabel('time (s)', font)
ylabel('voltage (mV)', font)
Legends A legend is a box (by default in upper right) associating labels with lines
(displayed as per their formats)
legend(lines, labels)
where lines is a tuple of lines, labels a tuple of corresponding strings
from pylab import *
lines = plot([1,2,3],'b-',[0,1,2],'r--')
legend(lines, ('First','Second'))
savefig('legend')
If there’s only 1 line, be sure to include the commas in the tuples
lengend((line1,), (‘Profit’,))
Use keyword argument loc to override the default location Use predefined strings or integer codes
‘upper right’ 1
‘upper left’ 2
‘lower left’ 3
‘lower right’ 4
‘right’ 5
‘center left’ 6
‘center right’ 7
‘lower center’ 8
‘upper center’ 9
‘center’ 10
E.g.,
legend((line,), (‘Profit’,) , loc=2)
Writing Mathematical Expressions Can use TeX markup in any text element
For usage, requirements, backend info, see mathtext documentation
http://matplotlib.sourceforge.net/api/mathtext_api.html
Use raw strings (precede the quotes with an 'r')
Surround the string text with $’s (as in TeX)
title(r'$\alpha > \beta$')
Regular text and mathtext can be interleaved within the same string
To make subscripts and superscripts use '_' and '^‘—e.g.,
title(r'$\alpha_i > \beta_i$')
Can use many TeX symbols, e.g.,
\infty, \leftarrow, \sum, \int
The over/under subscript/superscript style is supported
E.g., to write the sum of xi, i from 0 to ,
text(1, -0.6, r'$\sum_{i=0}^\infty x_i$')
Default font is italics for mathematical symbols
To change fonts, e.g., to write “sin” in Roman, enclose the text in a font command—e.g.,
text(1,2, r's(t) = $\mathcal{A}\mathrm{sin}(2 \omega t)$')
Many commonly used function names typeset in a Roman font have shortcuts
The above could be written as
text(1,2, r's(t) = $\mathcal{A}\sin(2 \omega t)$')
Font choices
Roman \mathrm
italics \mathit
caligraphy \mathcal
typewriter \mathtt
Accents :
\hat, \breve, \grave, \bar, \acute, \tilde, \vec, \dot, \ddot
E.g., overbar on an “o”: \bar{o}
from pylab import *
t = arange(0.0, 2.0, 0.01)
s = sin(2*pi*t)
plot(t,s)
title(r'$\alpha_i > \beta_i$', fontsize=20)
text(1, -0.6, r'$\sum_{i=0}^\infty x_i$', fontsize=20)
text(0.6, 0.6, r'$\mathcal{A}\mathrm{sin}(2 \omega t)$',
fontsize=20)
xlabel('time (s)')
ylabel('volts (mV)')
savefig('mathtext_tut', dpi=50)
Axes Properties There’s a current instance of Axes in the current figure
Contains all the graphical elements
gca() returns the current instance of Axes
cla() clears it
The following are a few get_ methods, all with no arguments
Most self-explanatory
get_legend()
get_lines()
get_title()
For the x axis
get_xlabel()
get_xbound() Returns the x-axis numerical bounds in the form of a tuple
(lbound, ubound)
get_xlim() Like get_xbound(), but returns an array
Similar get_ methods for the y axis
Corresponding commands for setting Axes properties
Use object methods (set_) or setp()
If a 2-element tuple or array is returned, method takes 2 corresponding arguments
Grids Use grid() function or grid() Axes method
With no arguments, gives a dotted black line at each tick on both axes
To suppress the grid, use grid(None)
Or simply grid() when there’s already a grid
Takes keyword arguments
grid(color='r', linestyle='-', linewidth=2)
Axes get_ methods
get_xgridlines()
get_ygridlines()
Corresponding set_ methods, or use setp()
Axis Scales Scale of either axis can be linear or log (default base 10)
Axes methods
set_xscale(s)
set_yscale(s) s either ‘linear’ or ‘log’
Corresponding set_ methods, or use setp()
from pylab import *
gca().set_yscale('log')
plot([1,10,100])
savefig('logscale')
Multiple Axes For control over axes placement, use function axes()
Can be initialized with a rectangle [left, bottom, width, height] in relative figure coordinates
(0, 0) is the bottom left of the of the figure canvas
Its width and height are 1
Several ways to use axes(); all return an Axes instance
axes()
Creates a default full window axis or returns the current Axes instance
axes([0.25, 0.25, 0.5, 0.5], axisbg=’g’)
Creates and displays a new axis offset by ¼ of the figure width and height on all sides
axes(ax)
where ax is an Axes instance, makes ax current
Allows multiple axes in the same figure
Objects are placed in the current Axes instance
from pylab import *
plot([0.2, 0.4, 0.6, 0.8, 3])
ax1 = gca()
ax2 = axes([0.25,0.45,0.25,0.25], axisbg='y')
axes(ax1)
plot([0.1,0.2,0.3,0.4,2], 'r--')
axes(ax2)
plot([1,2,3])
savefig('axes')
Multiple Subplots Functions axes() and subplot() both used to create axes
subplot() used more often
subplot(numRows, numCols, plotNum)
Creates axes in a regular grid of axes numRows by numCols
plotNum becomes the current subplot Subplots numbered top-down, left-to-right
1 is the 1st number
Commas can be omitted if all numbers are single digit
Subsequent subplot() calls must be consistent on the numbers or rows and columns
subplot() returns a Subplot instance
Subplot is derived from Axes
Can call subplot() and axes() in a subplot
E.g., have multiple axes in 1 subplot
See the Tutorial for subplots sharing axis tick labels
from pylab import *
subplot(221)
plot([1,2,3])
subplot(222)
plot([2,3,4])
subplot(223)
plot([1,2,3], 'r--')
subplot(224)
plot([2,3,4], 'r--')
subplot(221)
plot([3,2,1], 'r--')
savefig('subplot')
Event Handling All GUIs provide event handling to determine things like key
presses, mouse position, button clicks
matplotlib supports several GUIs
Provides an interface to the GUI event handling via the connect() and disconnect() methods of the pylab interface
matplotlib uses a callback event handling mechanism
Register an event that you want to listen for
The figure canvas calls a user defined function when that event occurs
E.g., to print to the console where the user clicks a mouse on your figure, define a function
def click(event):
print 'you clicked', event.x, event.y
Then register it with the event handler
connect('button_press_event', click)
When the user clicks in the figure canvas, the function is called and passed a MplEvent instance
The event instance has the attributes shown in the next slide
x x position - pixels from left of canvas
y y position - pixels from bottom of canvas
button button pressed None, 1, 2, 3
inaxes the Axes instance if mouse is over axes (or None)
xdata x coord of mouse in data coords (None if mouse isn't over axes)
ydata y coord of mouse in data coords (None if mouse isn't over axes)
name The string name of the event
canvas The FigureCanvas instance the event occurred in
key The key pressed if any, e.g., 'a', 'b', '1'. Also records 'control' and 'shift'
Can connect to events
‘button_press_event’
‘button_release_event’
‘motion_notify_event’
Complete example
from pylab import *
plot(arange(10))
def click(event):
if event.inaxes: print "(%-5.2f, %5.2f)" % (event.xdata, event.ydata)
connect('button_press_event', click)
show()
Bar Charts Function bar() creates a bar chart
Most of the arguments may be either scalars or sequences
Say in […] what they normally are
Required arguments
left x coordinates of the left sides of the bars [sequence]
height height of the bars [sequence]
Some optional keyword arguments
orientation orientation of the bars (‘vertical’ | ‘horizontal’)
width width of the bars [scalar]
color color of the bars [scalar]
xerr if not None,
generates error ticks on top the bars [sequence]
yerr if not None,
generates errorbars on top the bars [sequence]
ecolor color of any errorbar [scalar]
capsize length (in points) of errorbar caps (default 2) [scalar]
log False (default) leaves the orientation axis as is,
True sets it to log scale
For the following example, need the following
yticks(seq, labels)
Make the ticks on the y axis at y-values in seq with labels the corresponding elements of labels
Without labels, number as per seq
xticks(seq, labels)
Same, but for the x axis
xlim(xmin, xmax)
The values on the x axis go from xmin to xmax
from pylab import *
labels = ["Baseline", "System"]
data = [3.75, 4.75]
yerror = [0.3497, 0.3108]
xerror = [0.2, 0.2]
xlocations = array(range(len(data)))+0.5
width = 0.5
csize = 10
ec = 'r'
bar(xlocations, data, yerr=yerror, width=width,
xerr=xerror, capsize=csize, ecolor=ec)
yticks(range(0, 8))
xticks(xlocations + width/2, labels)
xlim(0, xlocations[-1]+width*2)
title("Average Ratings on the Training Set")
savefig('bar')
An Aside: Artists, Patches, & Collections When we execute this bar chart example in ipython, command
bar(xlocations, data, yerr=yerror, width=width, xerr=xerror,
capsize=csize, ecolor=ec)
returns
[<matplotlib.patches.Rectangle object at 0x01C9F930>,
<matplotlib.patches.Rectangle object at 0x02AC0A90>]
That is, each bar in the graph is an instance of the class
matplotlib.patches.Rectangle
The Patches class has subclasses for geometric figures
The 3 Conceptual Parts of the matplotlib Code The matplotlib code is divided conceptually into 3 parts:
1. the matlab interface
Module pylab is mainly code to manage the multiple figure windows across backends to provide a thin, procedural wrapper around the object oriented
plotting code
2. the matplotlib Artists
a series of classes that derive from matplotlib.artist.Artist
So named because they're the objects that actually draw into the figure
3. the backend renderers, each implementing a common drawing interface that actually puts the ink on the paper—e.g.,
create a postscript document
call the gtk drawing code
The matplotlib Artist hierarchy
The primitive Artists are classes Patch, Line2D, Text, AxesImage, FigureImage and Collection
All other artists are composites of these
E.g., a Tick is comprised of a Line2D instance (tick line) and a Text instance (tick label)
The Artist Containment Hierarchy
Attribute names in lower case Object type listed below in upper case
If the attribute is a sequence, the connecting edge is labeled 0. . .n the object type is in [..]
Some redundant information omitted—e.g.,
yaxis contains the equivalent objects that xaxis contains
minorTicks have same containment hierarchy as majorTicks
Some matplotlib.patches ClassesCircle(xy, radius, **kwargs) A circle of the given radius centered at xy, a tuple (x, y )
Some keyword arguments
edgecolor (or ec) any matplotlib color
facecolor (or fc) any matplotlib color
fill True | False
Rectangle(xy, width, height, **kwargs) A rectangle with lower left corner at xy of the given width and height
Same keyword arguments as Circle
Polygon(xys, **kwargs) xys is a NumPy array of shape N 2, where N is the number of vertices
Same keyword arguments as Circle
Keyword argument zorder Default drawing order (what’s on top of what) for axes is patches,
lines, text
Within same class, by default, what’s specified later is on top what’s drawn earlier
Override this with the zorder argument, with integer values
Higher z-orders are on top lower
zorder must be defined for all graphical objects for it to have an effect
Drawing Patches If p is a patch, it must be added to the axes with the Axes instance
method add_patch(p)
For patches to appear, must invoke draw()
from matplotlib.patches import Rectangle, Circle
from pylab import *
ax = gca()
r = Rectangle((0.1,0.1), 0.5, 0.5, fill=False, zorder=2, ec="r")
ax.add_patch(r)
c = Circle((0.7,0.7), 0.25, zorder=1, fc="y")
ax.add_patch(c)
draw()
savefig('my_patches')
Collections of Patches Package matplotlib.collections contains classes for efficiently drawing
collections of objects sharing most properties
http://matplotlib.sourceforge.net/api/collections_api.html
PatchCollection is derived from class Collection
PatchCollection(patches, match_original=False, **kwargs)
patches is a sequence of Patch objects
If match_original is True, use colors and line-widths of original patches If False, can use the standard keyword arguments (edgecolor,
facecolor, …), applying to patches Can’t use abbreviations (e.g., ec)
If ps is a patch collection, must use Axes instance method add_collection(ps)
No need for draw()
from matplotlib.patches import Polygon
from matplotlib.collections import PatchCollection
from pylab import *
poly1 = Polygon([[0.4,0.4],[0.8,0.3],[0.9,0.9],[0.3,0.5]])
poly2 = Polygon([[0.1,0.1],[0.4,0.4],[0.1,0.4]])
ps = PatchCollection([poly1,poly2], edgecolor='b', facecolor='y')
gca().add_collection(ps)
savefig('my_patch_collection')
Histogramshist(x, bins=n )
Computes and draws a histogram
x: a sequence of numbers (usually with many repetitions)
If keyword argument bins is an integer, it’s the number of (equally spaced) bins
Default is 10
from pylab import *
import numpy
x = numpy.random.normal(2, 0.5, 1000)
hist(x, bins=50)
savefig('my_hist')
hist() returns a tuple (n, bins, patches ), where
n is an array of the bin values,
bins is an array of the bin limits, and
patches is an array of the rectangles plotted
In the shell (with x determined as above),
hist(x, bins=5)
returns
(array([ 1, 35, 406, 483, 75]), array([-0.34300571, 0.40693226, 1.15687024, 1.90680822,
2.65674619, 3.40668417]),
<a list of 5 Patch objects>)
bins can be a sequence of floating point numbers Each is the x valued of a bin edge
So the 1st bin is from bins[0] to bins[1], etc.
Allows for unequally spaced bin
Other Keyword Arguments range Lower and upper range of the bins,
No effect if bins is a sequence
Outliers ignored
normed If True, the array of bin values returned contains the counts
normalized to form a probability density (summing to 1)
cumulative If True, each bin gives the count for that bin plus all bins for smaller
values
histtype: the style drawn
‘bar’: traditional bar style
‘barstacked’: a bar style, multiple data stacked on top each other
‘step’: a line plot by default unfilled
‘stepfilled’: a line plot by default filled
align (values ‘left’, ‘mid’, ‘right’) Whether the bars are centered
on the left bin edges, between bin edges, or on the right bin edges
rwidth Relative width of bars as a fraction of bin width
If None, width automatically computed
Ignored if histtype=’step’
Log If True, axes have a log scale
Empty bins filtered out
Other usual keyword arguments: edgecolor (or ec), facecolor (or fc), fill, linewidth, etc.
NumPy Histogramshistogram (x, **kwargs)
x is as with matplotlib hist(x, **kwargs)
Returns a tuple (n, bins)
Just like the matplotlib function hist(x, **kwargs) returns a tuple (n, bins, patches)
But without the patches
Doesn’t draw a figure
Other keyword arguments:
range (default None)
normed (default 0, i.e., False)
Same as the hist() arguments of the same name
from pylab import *
import numpy
mu, sigma = 2, 0.5
# Vector of 10000 normal deviates with STD 0.5 and mean 2
v = numpy.random.normal(mu,sigma,10000)
hist(v, bins=50, normed=1) # matplotlib version (plot)
(n, bins) = numpy.histogram(v, bins=50, normed=1) # no plot
plot(bins, n, 'r', linewidth=2)
savefig('histnumpy')
For next example, need the numpy function
rand (d1, d2, . . ., dn )
Returns an array of shape (d1, d2, . . . , dn ) of uniform random numbers in the interval [0, 1)
This example constructs a 3030 array of random numbers in the interval [0,1)
Draws histograms of the normalized row and column sums (marginal densities)
from numpy import *
from pylab import *
v = rand(30,30)
csum = v.sum(axis=0)
rsum = v.sum(axis=1)
teen_bins = arange(10,20)
subplot(121)
hist(csum, bins=teen_bins, normed=True)
title('Marginal Density x')
subplot(122)
hist(rsum, bins=teen_bins, normed=True)
title('Marginal Density y')
savefig('twoDhist')
histogram2d(x, y, **kwargs) Keywords arguments again are
bins (default 10)
range (default None)
normed (default False)
Returns a tuple (H, xedges, yedges )
xedges and yedges are arrays of floating point numbers Define the edges of the 2D bins at the x and y values, resp.
H is oriented such that H [i,j ] is the number of samples in binx[j] and biny[i] Associate x with j, y with i
With normed=True, get a density (not a bin-count)
Marginal densities got by summing rows or summing columns
>>> H, xedges, yedges = histogram2d(rand(100),rand(100),bins=5)
>>> print H.sum(axis=0)
[ 21. 26. 13. 20. 20.]
>>> print xedges
[ 0.01034873 0.20348935 0.39662997 0.58977059 0.7829112 0.97605182]
>>> print H.sum(axis=1)
[ 23. 15. 23. 24. 15.]
>>> print yedges
[ 2.86000121e-05 1.99003906e-01 3.97979212e-01 5.96954518e-01 7.95929824e-01 9.94905130e-01]
histogramdd([[x0,0, x0,1, …, x0,D-1], …, [xN-1,0, xN-1,1, …, xN-1,D-1]]), **kwargs)
Generalizes histogram2d()
The 1st argument is a length-N array of length-D arrays (samples)
Scatter Plotsscatter(x, y )
x and y are arrays of numbers of the same length, N
Makes a scatter plot of x vs. y
from pylab import *
N = 20
x = 0.9*rand(N)
y = 0.9*rand(N)
scatter(x,y)
savefig('scatter_dem')
Keyword Argumentss If an integer, size of marks in points2 , i.e., area occupied (default 20)
If an array of length N, gives the sizes of the corresponding elements of x, y
marker Symbol marking the points (default = ‘o’)
Same options as for lines that don’t connect the dots And a few more
c A single color or a length-N sequence of colors
from pylab import *
N = 30
x = 0.9*rand(N)
y = 0.9*rand(N)
area = pi * (10 * rand(N))**2 # 0 to 10 point radius
scatter(x,y,s=area, marker='^', c='r')
savefig('scatter_demo')
Ticks A tick is a cross mark on an axis with an associated label
xticks (on the x axis) and yticks (on the y axis)
xticks() returns a tuple of
an array of tick locations (numbers) on the x axis
an array of corresponding tick labels (text)
yticks() is the same, but for the y axis
>>> plot([1,2,3,4], [1,4,9,16])
[<matplotlib.lines.Line2D object at 0x02AC2190>]
>>> xlocs, xlabs = xticks()
>>> ylocs, ylabs = yticks()
>>> print xlocs, '\n', xlabs, '\n', ylocs, '\n', ylabs
[ 1. 1.5 2. 2.5 3. 3.5 4. ]
<a list of 7 Text xticklabel objects>
[ 0. 2. 4. 6. 8. 10. 12. 14. 16.]
<a list of 9 Text yticklabel objects>
xticks() and yticks() can also take 1 or 2 (or more) arguments to set tick features
With 1 argument, it’s an array of new locations for the ticks—e.g.,
xticks( arange(6) )
With 2 arguments, they’re the locations (as with 1) and an array of corresponding labels—e.g.,
xticks([1, 2, 3], [‘Al’, ‘Ed’, ‘Ken’])
xticks() and yticks() can also take text keyword arguments
In all cases, xticks() and yticks() return a tuple of an array of locations and an array of labels
Some tick-related Axes instance methods Note: Minor ticks are the (usually smaller) ticks that occur
between the major ticks (the usual ticks)
get_xticklabels(),
get_xmajorticklabels()
get_xminorticklabels()
get_xticklabels(minor=False)
get_xticklines()¶
get_xticks(minor=False) Return the x ticks as a list of locations
Corresponding y methods
Corresponding set_ methods
>>> plot([1,2,3])
[<matplotlib.lines.Line2D object at 0x01C9C110>]
>>> gca().set_xticks([0.25, 0.75, 1.25, 1.75, 2.25, 2.75], minor=True)
[<matplotlib.axis.XTick object at 0x00B3B770>,
<matplotlib.axis.XTick object at 0x02AC9C10>,
<matplotlib.axis.XTick object at 0x02AC9F90>,
<matplotlib.axis.XTick object at 0x02AC9FF0>,
<matplotlib.axis.XTick object at 0x02AD4390>,
<matplotlib.axis.XTick object at 0x02AD47B0>]
>>> draw()
Note the small ticks on the x axis
For the following example:
Text property rotation is the angle of the text object relative to the x axis Values, besides numbers (degrees), can be ‘horizontal’ (default)
and ‘vertical”
from pylab import *
plot([1,2,3,4], [1,4,9,16])
locs, labels = xticks([1,2,3,4], ['Frogs','Hogs','Bogs','Slogs'])
setp(labels, 'rotation', 'vertical')
savefig('ticks_simpler')
Tick Locators and Formatters Module matplotlib.ticker has 2 bases classes: Locator,
Formatter
Each axis (xaxis or yaxis) has
a major and minor tick locator and
The default minor tick locators return the empty list By default, no minor ticks
a major and minor tick formatter
Each can be set independently
A user can create and plug-in a custom tick locator or formatter
Locators handle
autoscaling of the view limits based on the data limits
choosing the tick locations
Class MultipleLocator
Most generally useful tick locator
Initialize it with a base
It picks axis limits and ticks that are multiples of the base
Class AutoLocator
Contains a MultipleLocator instance
Dynamically (& intelligently) updates it based on the data & zoom limits
Class Summary
NullLocator No ticks
IndexLocator Locator for index plots (e.g., where 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
The Basic Tick Locators
To override the default locator,
use a locator and pass it to the x or y axis instance with one of (where ax is the current axes object)
ax.xaxis.set_major_locator( xmajorLocator )
ax.xaxis.set_minror_locator( xminorLocator )
ax.yaxis.set_major_locator( ymajorLocator )
ax.yaxis.set_minor_locator( yminorLocator )
Tick Formatting Formatters control conversion of the numeric tick location into a string
A formatter operates on a single tick value (and its tick position)
Returns a string to the axis
Class Summary
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
The Tick Formatting Classes
To control the major and minor tick label formats,
use one of the following (where ax is an Axes instance)
ax.xaxis.set_major_Formatter( xmajorFormatter )
ax.xaxis.set_minor_Formatter( xminorFormatter )
ax.yaxis.set_major_Formatter( ymajorFormatter )
ax.yaxis.set_minor_Formatter( yminroFormatter )
from pylab import *
# import the tick locator and formatter class
from matplotlib.ticker import MultipleLocator, FormatStrFormatter
majorLocator = MultipleLocator(21) # multiples of 21
majorFormatter = FormatStrFormatter('*%d*')
minorLocator = MultipleLocator(7) # multiples of 7
minorFormatter = FormatStrFormatter('%d')
t = arange(0.0, 100.0, 0.1)
s = sin(0.1*pi*t)*exp(-t*0.01)
plot(t, s)
ax = gca()
ax.xaxis.set_major_locator(majorLocator)
ax.xaxis.set_major_formatter(majorFormatter)
ax.xaxis.set_minor_locator(minorLocator)
ax.xaxis.set_minor_formatter(minorFormatter)
grid(True)
savefig('ticks_simple')
Plotting Dates To plot dates, matplotlib provides converter functions to convert
python datetime objects to and from floating point numbers
Represent days in the Gregorian Calendar UTC time
No daylight savings time or timezone offset
But timezone support is provided See the pytz module (http://pytz.sourceforge.net/)
The supported date range is the same as the Python datetime module: years 0001-9999
3 datetime conversion functions.
date2num() takes a (sequence of) python datetime(s) Returns a (sequence of) float(s)
num2date() does the inverse
drange() takes a start date, end date and datetime timedelta object
Returns a sequence of floats
Function plot_date() plots y-values vs. floating point dates
Uses plot() but picks a date tick locator and a date tick formatter makes an intelligent default choice based on the range of dates
To use custom date tickers and formatters, use plot()
from pylab import *
import datetime
date1 = datetime.date( 1998, 1, 1 )
date2 = datetime.date( 2004, 4, 12 )
delta = datetime.timedelta(days=100)
dates = drange(date1, date2, delta)
s = rand(len(dates))
plot_date(dates, s)
locs, labels = xticks()
setp(labels, rotation=45)
grid(True)
fig = gcf()
dsize = fig.get_size_inches()
fig.set_size_inches( 2 * dsize[0], dsize[1] )
savefig('tick_dates_simple')
Locating and Formatting Date LabelsClass Summary
MinuteLocator Locate minutes
HourLocator Locate hours
DayLocator Locate specified days of the month
WeekdayLocator Locate days of the week, e.g., MO, TU
MonthLocator Locate months, e.g., 7 for July
YearLocator Locate years that are multiples of base
RRuleLocator Locate using a matplotlib.dates.rrulewrapper. The rrulewrapper is a simple wrapper around a dateutils.rrule
The Tick Locators Specialized For Date Plots • In the matplotlib.dates module
E.g., for a month tick every quarter, use
months = MonthLocator(range(3,13,3))
For full control of date ticking, use your own rule with the RRuleLocator class
DateFormatter sub-class of Formatter takes a strftime() format string
from pylab import *
import datetime
years = YearLocator(2) # every 2 years
months = MonthLocator(range(3,13,3)) # every quarter
yearsFmt = DateFormatter('%y') # only last 2 digits
ax = gca()
ax.xaxis.set_major_locator(years)
ax.xaxis.set_major_formatter(yearsFmt)
ax.xaxis.set_minor_locator(months)
date1 = datetime.date( 1998, 1, 1 )
date2 = datetime.date( 2004, 4, 12 )
delta = datetime.timedelta(days=100)
dates = drange(date1, date2, delta)
s = rand(len(dates))
plot_date(dates, s)Continued
locs, labels = xticks()
setp(labels, rotation=45)
grid(True)
fig = gcf()
dsize = fig.get_size_inches()
fig.set_size_inches( 2 * dsize[0], dsize[1] )
savefig('tick_dates')
Odds and EndsHorizontal and Vertical Lineshlines(y, xmin, xmax )
Draw horizontal lines at heights given by the numbers in array y
If xmin and xmax are arrays of same length as y, they give the left and right endpoints of the corresponding lines, resp.
If either is a scalar, all lines have the same endpoint, specified by it
Some keyword arguments
linewidth (or lw): line width in points
color: default ‘k’
vlines(x, ymin, ymax ) is similar but for vertical lines
Axis Lines axhline() draws a line on the x axis spanning the horizontal
extent of the axes
axhline(y ) draws such a line parallel to the x axis at height y
Some keyword arguments
color: default ‘b’
label
linewidth in points
axvline() is similar but w.r.t. the y axis
Grid Lines grid(True) produces grid lines at the tick coordinates
grid(None) suppresses the grid
grid() toggles the presence of the grid
Some keyword arguments
color: default ‘k’
linestyle: default ‘:’
linewidth
Some Axes instance methods
get_xgridlines()
get_ygridlines()
Example:
setp(gca().get_xgridlines(), color='r')
Resizing the Figure Often should make the figure wider or higher so objects aren’t cramped
Use Figure instance methods get_size_inches() and set_size_inches()
To get an array of the 2 dimensions in inches (width then height):
fig = gcf()
dsize = fig.get_size_inches()
E.g., to double the width
fig.set_size_inches( 2 * dsize[0], dsize[1] )
See the example in the SciPy Cookbook
http://www.scipy.org/Cookbook/Matplotlib/AdjustingImageSize
3D Matplotlib: mplot3d See http://matplotlib.org/mpl_toolkits/mplot3d/tutorial.html
An Axes3D object is created like any other axes, but using the projection='3d' keyword
Create a new matplotlib.figure.Figure and add to it a new axes of type Axes3D
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D
fig = plt.figure()
ax = fig.add_subplot(111, projection='3d')
Example: Line PlotsAxes3D.plot(xs, ys, *args, **kwargs)
Plot 2D or 3D data
xs, ys are the arrays of x, y coordinates of vertices
zs is the z value(s), either 1 for all points or (as array) 1 for each point
zdir gives which direction to use as z (‘x’, ‘y’ or ‘z’) when plotting a 2D set
Other arguments are passed on to plot()
Example
import matplotlib as mpl
from mpl_toolkits.mplot3d import Axes3D
import numpy as np
import matplotlib.pyplot as plt
mpl.rcParams['legend.fontsize'] = 10
fig = plt.figure()
ax = fig.gca(projection='3d')
theta = np.linspace(-4 * np.pi, 4 * np.pi, 100)
z = np.linspace(-2, 2, 100)
r = z**2 + 1
x = r * np.sin(theta)
y = r * np.cos(theta)
ax.plot(x, y, z, \ label='parametric curve')
ax.legend()
plt.show()
AnimationThe Old Way To take an animated plot and turn it into a movie,
save a series of image files (e.g., PNG) and
use an external tool to convert them to a movie
Can use mencoder, part of the mplayer suite
See http://www.mplayerhq.hu/design7/news.html
Can download binaries for Windows
Or use ImageMagick’s convert (“the Swiss army knife of image tools”)
See http://www.imagemagick.org/script/convert.php
Matplotlib Animation Matplotlib Animation Tutorial
http://jakevdp.github.com/blog/2012/08/18/matplotlib-animation-tutorial/
Matplotlib animation documentation
http://matplotlib.org/api/animation_api.html
Matplotlib animation examples
http://matplotlib.org/examples/animation/
Official and good, but documentation limited to meager program comments The tutorial (above) goes through several of these
Alias http://matplotlib.sourceforge.net/examples/animation/index.html
This replaces the Cookbook examples
http://www.scipy.org/Cookbook/Matplotlib/Animations