For these plots, I’m assuming the code in the “Setup” section below has been run (to import pylab and to create some fake data).

• x is the x data
• y is the y data
• e, f, g, and h are different errors. Why four? Because not only can you have horizontal and vertical errorbars but you can have asymmetrical error bars as well. It’s possible to plot four different errors for each point in the four directions -x, +x, -y and +y.

Note that the errors are randomly generated, so the plots below won’t exactly like your plots even if you run the same code.

Getting your own error estimates

Here is an excellent and very readable differences between standard error and standard deviation and when to use each. Guaranteed you’ll feel more comfortable about standard error and standard deviation after reading this.

If you need to generate your own error bars, you can use (for example) the NumPy function std() — but be warned: this function divides by N, not N-1 (degrees of freedom) so be careful with small sample sizes.

The setup (will be assumed for all following code)

If you started IPython with the -pylab switch, the plots should show up immediately when you use the plotting commands below.

If you did not start IPython with the -pylab switch, then you will need to type show() to display the plots. You will also have to close all plots before being able to get back to the command line.

from pylab import *

x = arange(0.1, 4, 0.1)
y = exp(-x)
e = 0.1*abs(randn(len(y)))
f = 0.1*abs(randn(len(y)))
g = 2*e
h = 2*f

Vertical symmetric errorbars

(probably the most common use)
This one has red circles as the marker format, “ro“.

figure()
errorbar(x, y, yerr=e, fmt='ro')

Vertical error bars

Horizontal symmetric errorbars

This one has a format of blue dots (“b.”) and instead of using “yerr” uses “xerr”

figure()
errorbar(x, y, xerr=f, fmt='b.')

Horizontal error bars

Symmetric x and symmetric y

Back to the red circles. This time, both xerr and yerr are used.

figure()
errorbar(x, y, yerr=e, xerr=f, fmt='ro')

Symmetrical error bars

Asymmetric error bars

The trick for asymmetric error bars is to pass a list-of-lists (or a 2-D array) as xerr and yerr. The item in the list is for negative error, the second one for positive error. So in this case, -y error is e, +y is g, -x is f, and +x is h.

figure()
errorbar(x, y, yerr=[e,g], xerr=[f,h], fmt='ro')

Aysmmetric error bars

Customizing

Here’s an example of the kinds of things you can change in a plot. See the help for plot and errorbar for more.

In this case I made the points be dots, made the line color black, gave the errorbars a red color, made the markers blue, gave the series a label, changed the errorbar cap size to zero, and made the line style a solid line.

Then I added 0.5 to the y values for a quick way of getting a second line. I plotted this second line with different formatting commands.

Then I added x and y axis labels, a legend (which used the labels provided in the plotting commands) and finally a title.

errorbar(x, y,
           yerr=e,
           marker='.',
           color='k',
           ecolor='r',
           markerfacecolor='b',
           label="series 1",
           capsize=0,
           linestyle='-')

# Add a second series with different errorbar formatting.
errorbar(x, y+0.5,
           yerr=h,
           marker='o',
           color='k',
           ecolor='k',
           markerfacecolor='g',
           label="series 2",
           capsize=5,
           linestyle='None')

xlabel('x axis label')
ylabel('y axis label')
legend()
title('Customized plot with errorbars')

Yep, it’s ugly . . . please don’t use these formatting choices in real life! My intention here is just to show you how to make tweaks to your plot.

Custom error bars

View the rc parameters by using

import pylab as p
print p.rcParams

Examples ensue.

Where is matplotlibrc?

On my machine (Ubuntu 7.10) it’s in /usr/lib/python2.5/site-packages/matplotlib/mpl-data/matplotlibrc. If I wanted to customize it, I could put a copy in ~/.matplotlib/matplotlibrc. If you’re on Windows, you can put a copy in C:\Documents and Settings\yourname\.matplotlib

Editing this file makes changes that are in effect every time you use matplotlib.

To make temporary changes, use the pylab.rc function or set values in the rcParams dictionary. I’ll describe both ways below.

An example

For example, I want to make a series of plots for a manuscript. The default font size is a little too small for these plots, and tweaking the font size for every one of the plots would be tedious. Let’s see what my rc options are.

import pylab as p
p.rcParams

Among a large number of options, I see some that will be of use:

...
...
'axes.labelsize': 12.0,
...
'xtick.labelsize': 12.0,
...
'ytick.labelsize': 12,0,
...

Two ways to change settings

It’s personal preference which one you use. Either way, you only have to do this once. From then on, all plots will use these new parameters, until you reset the parameters using rcdefaults()

Using rcParams, I could set the properties like this:

rcParams['axes.labelsize'] = 16.0
p.rcParams['xtick.labelsize'] = 16.0
p.rcParams['ytick.labelsize'] = 16.0

Alternatively, I could use rc:

p.rc(('xtick','ytick','axes'), labelsize=16.0)

Now, plot!

p.plot([1,2,3])
p.xlabel('x axis')
p.ylabel('y axis')
p.show()

Here’s the new figure. Any other figure I make will have the same text size.

Until, that is, I reset to the defaults:

p.rcdefaults()

The result is this:

import pylab as p
p.rc(('xtick.major','xtick.minor','ytick.major','ytick.minor'), pad=10)
p.plot([1,2,3])

If you only want to change one of the tick labels, say, the x major ticks, use
p.rc(‘xtick.major), pad=10)

When you’re done and want to reset the rc settings, use

p.rcdefaults()

See matplotlibrc for more settings you can change via the rc command.

Here’s a slightly simplified version of the code, and afterward a detailed explanation of what’s going on.

from pylab import *

x = [1,2,3,4,5]
y1 = [10,25,30,45,50]
y2 = [1,3,4,7,12]

ax1 = subplot(111)

plot(x, y1, 'b-')

ax2 = twinx()

plot(x, y2, 'r--')
show()

Step-by-step explanation.

Basically, we make two separate axes right on top of each other. The data in y1 will go on the first created axes, and y2 will go on the second created axes. The key to this is the twinx() function. What it does is explained below.







What’s happening here? twinx() duplicates the current set of axes (the current set of axes is ax1). The source code of twinx() has a line like this:

ax2 = gcf().add_axes(ax1.get_position(), sharex=ax1, frameon=False)

Which:

• adds a new set of axes to the current figure (that’s the gcf() part).
• puts the new set of axes in the same position as ax1 (that’s the ax1.get_position() part)
• makes the new set of axes have an x axis with the same properties as the first axes, ax1. When you pan or zoom the figure both axes will move together.
• returns the new axis

The result is a new set of axes right on top of the old one, ready and primed for some plotting.

The rest of the code plots a red dashed line in the new axes using the data in y2, and the show() command shows your handiwork.
*not really magic

Final product

Oh no! I forgot to label the axes!

The nice thing about saving the axes as ax1 and ax2 is that you can change either one of them at any time. Just call any one of the 280 possibilities (In IPython, type ax1, then a “.”, then the tab key — that is, ax1.[TAB] — for a list of what axes can do).

For example, you can use the set_ylabel() method of each axes object.

ax1.set_ylabel('first y-axis')
ax2.set_yabel('second y-axis')

If you have already used show(), then your changes WON’T immediately be updated. This is by design, in case you are adding many things to a figure and don’t want to refresh after every little thing you add. Once you’re ready to redraw the figure, Use

draw()

You can label the x axis too, but you’ll only need to choose either ax1.set_xlabel(‘x label here’) or ax2.set_xlabel(‘x label here’). You can remove an axis label by just setting it to an empty string: ax2.set_xlabel(”).

With labels, it looks something like this:

More than two y-axes?

Unfortunately, this is not yet implemented in matplotlib but it’s on the wishlist, as this post describes, along with a suggestion to use PyX instead of matplotlib for a graph of this type.

Fire up IPython and matplotlib.

plain ol’ bar plot

# pylab contains matplotlib plus other goodies.
import pylab as p

#make a new figure
fig = p.figure()

# make a new axis on that figure. Syntax for add_subplot() is
# number of rows of subplots, number of columns, and the
# which subplot. So this says one row, one column, first
# subplot -- the simplest setup you can get.
# See later examples for more.

ax = fig.add_subplot(1,1,1)

# your data here:

x = [1,2,3]
y = [4,6,3]

# add a bar plot to the axis, ax.
ax.bar(x,y)

# after you're all done with plotting commands, show the plot.
p.show()

Here’s what it looks like:

This is just the basic bar plot. Not that great for publication . . . it needs better colors, some labels, and maybe some error bars. The scripts below walk you through doing just that.

barplot-2.py

Now let’s tweak it out a little . . . this time we’ll make two subplots, one with the same plotting commands as above, and the other subplot with red, thinner bars.

import pylab as p

fig = p.figure()

# Here we're adding 2 subplots.  The grid is set
# up as one row, two columns.
ax1 = fig.add_subplot(1,2,1)
ax2 = fig.add_subplot(1,2,2)

x = [1,2,3]
y = [4,6,3]

# first axis, with the same bar plot as before.
ax1.bar(x,y)

# on the second axis, make the width smaller (default is 0.8)
ax2.bar(x,y,width=0.3, facecolor='red')
ax2.set_ylabel('number of widgets')

p.show()

And the result:

barplot-3.py

OK, time to make it look nicer. This code may look like it’s long, but it’s mostly a bunch of comments explaining what everything does.

Added 1/28/07:
By the way, here are my notes for using errorbars in general with matplotlib.

import pylab as p
fig = p.figure()
ax = fig.add_subplot(1,1,1)

# note the change: I'm only supplying y data.
y = [4, 6, 7, 3, 5]

# Calculate how many bars there will be
N = len(y)

# Generate a list of numbers, from 0 to N
# This will serve as the (arbitrary) x-axis, which
# we will then re-label manually.
ind = range(N)

# I'm also supplying (fake) error for each y value.
# You can use numpy's standard deviation, numpy.std(data)
# to calculate error bars for your own data.
# Standard error is standard deviation over sqrt(N),
# so you could use numpy.std(x)/numpy.sqrt(len(x))
# to get standard error for the data in a list x.
err = [1.2, 1.5, 2.5, 1.2, 2.0]

# See note below on the breakdown of this command
ax.bar(ind, y, facecolor='#777777',
       align='center', yerr=err, ecolor='black')

#Create a y label
ax.set_ylabel('Counts')

# Create a title, in italics
ax.set_title('Counts, by group',fontstyle='italic')

# This sets the ticks on the x axis to be exactly where we put
# the center of the bars.
ax.set_xticks(ind)

# Labels for the ticks on the x axis.  It needs to be the same length
# as y (one label for each bar)
group_labels = ['control', 'cold treatment',
                 'hot treatment', 'another treatment',
                 'the last one']

# Set the x tick labels to the group_labels defined above.
ax.set_xticklabels(group_labels)

# Extremely nice function to auto-rotate the x axis labels.
# It was made for dates (hence the name) but it works
# for any long x tick labels
fig.autofmt_xdate()

p.show()

Here’s what the result looks like:

Note: Here’s the breakdown of the command used above,

ax.bar(ind, y, facecolor='#777777',
       align='center', yerr=err, ecolor='black')

:

• ind contains the x values to plot
• y contains the y values to plot
• the #777777 is the hexadecimal color code for a dark gray
• align tells the bar command to align the bars on the center of the x values we give it, instead of aligning the left side of the bar (which is the default)
• yerr specifies the error bars in the y direction.
• ecolor is the color of the error bars

By the way, here’s the un-commented, more compact version of the same exact code:

import pylab as p
fig = p.figure()
ax = fig.add_subplot(1,1,1)
y = [4, 6, 7, 3, 5]
N = len(y)
ind = range(N)
err = [1.2, 1.5, 2.5, 1.2, 2.0]
ax.bar(ind, y, facecolor='#777777',
       align='center', yerr=err, ecolor='black')
ax.set_ylabel('Counts')
ax.set_title('Counts, by group',fontstyle='italic')
ax.set_xticks(ind)
group_labels = ['control', 'cold treatment',
                     'hot treatment', 'another treatment',
                     'the last one']
ax.set_xticklabels(group_labels)
fig.autofmt_xdate()
p.show()

So what else can you tweak?

Just about everything. Below is the help entry for the bar function, which you can view in IPython by typing p.ax.bar? or p.bar?. Note, for example, that you can change things like the transparency of the bars, give each bar different widths, change the edge colors, change the size of the ‘caps’ on the error bars, and so on.

bar(left, height, width=0.8, bottom=0,
        color=None, edgecolor=None, linewidth=None,
        yerr=None, xerr=None, ecolor=None, capsize=3,
        align='edge', orientation='vertical', log=False)
    Make a bar plot with rectangles bounded by
      left, left+width, bottom, bottom+height
            (left, right, bottom and top edges)
    left, height, width, and bottom can be either scalars or sequences
    Return value is a list of Rectangle patch instances
        left - the x coordinates of the left sides of the bars
        height - the heights of the bars
    Optional arguments:
        width - the widths of the bars
        bottom - the y coordinates of the bottom edges of the bars
        color - the colors of the bars
        edgecolor - the colors of the bar edges
        linewidth - width of bar edges; None means use default
            linewidth; 0 means don't draw edges.
        xerr and yerr, if not None, will be used to generate errorbars
        on the bar chart
        ecolor specifies the color of any errorbar
        capsize (default 3) determines the length in points of the error
        bar caps
        align = 'edge' (default) | 'center'
        orientation = 'vertical' | 'horizontal'
        log = False | True - False (default) leaves the orientation
                axis as-is; True sets it to log scale
    For vertical bars, align='edge' aligns bars by their left edges in
    left, while 'center' interprets these values as the x coordinates of
    the bar centers. For horizontal bars, 'edge' aligns bars by their
    bottom edges in bottom, while 'center' interprets these values as the
    y coordinates of the bar centers.
    The optional arguments color, edgecolor, linewidth, xerr, and yerr can
    be either scalars or sequences of length equal to the number of bars.
    This enables you to use bar as the basis for stacked bar charts, or
    candlestick plots.
    Optional kwargs:
            alpha: float
            animated: [True | False]
            antialiased or aa: [True | False]
            axes: an axes instance
            clip_box: a matplotlib.transform.Bbox instance
            clip_on: [True | False]
            clip_path: an agg.path_storage instance
            edgecolor or ec: any matplotlib color
            facecolor or fc: any matplotlib color
            figure: a matplotlib.figure.Figure instance
            fill: [True | False]
            hatch: unknown
            label: any string
            linewidth or lw: float
            lod: [True | False]
            picker: [None|float|boolean|callable]
            transform: a matplotlib.transform transformation instance
            visible: [True | False]
            zorder: any number

    Addition kwargs: hold = [True|False] overrides default hold state</code>