Organizing matplotlib
November 27, 2012 at 8:11 PM by Dr. Drang
I’m proceeding slowly in my switch from Gnuplot to matplotlib. The biggest problem in the transition is the usability and organization of matplotlib’s documentation. I never liked the organization of Gnuplot’s docs (preferring Philipp Janert’s better organized Gnuplot in Action), but at least Gnuplot offers a hyperlinked table of contents with all its commands. Matplotlib’s pyplot documentation doesn’t even give you that. So tonight I made one and published it as a Gist.
The first several entries look like this when rendered:
| Method | Description |
|---|---|
| acorr | Plot the autocorrelation of x. |
| annotate | Create an annotation: a piece of text referring to a data point. |
| arrow | Add an arrow to the axes. |
| autoscale | Autoscale the axis view to the data (toggle). |
| autumn | set the default colormap to autumn and apply to current image if any. See help(colormaps) for more information |
| axes | Add an axes to the figure. |
| axhline | Add a horizontal line across the axis. |
| axhspan | Add a horizontal span (rectangle) across the axis. |
| axis | Set or get the axis properties.: |
It’s not great looking, and the descriptions of the methods are uneven in quality and brevity, but it’s a start. I generated it directly from the pyplot manual page via this script:
python:
1: #!/usr/bin/python
2:
3: from BeautifulSoup import BeautifulSoup
4: import urllib
5:
6: url = 'http://matplotlib.org/api/pyplot_api.html'
7: html = urllib.urlopen(url).read()
8: soup = BeautifulSoup(html)
9:
10: dls = soup.findAll('dl')
11:
12: print '''<html>
13: <head>
14: <title>matplotlib.pyplot contents</title>
15: <style type="text/css">
16: table {
17: border-collapse: collapse;
18: }
19:
20: table th {
21: padding: .5em 1em .25em 1em;
22: background-color: #ddd;
23: border: 1px solid black;
24: border-bottom: 2px solid black;
25: }
26:
27: table td {
28: padding: .25em 1em .25em 1em;
29: border: 1px solid black;
30: }
31: </style>
32: <head>
33: <body>
34: <h1>matplotlib.pyplot contents</h1>
35: <table>
36: <tr><th>Method</th><th>Description</th></tr>
37: '''
38: for d in dls:
39: dt = d.dt
40: dd = d.dd
41: id = dt.get('id')
42: if id:
43: method = id.split('.')[-1]
44: try:
45: desc = [ unicode(x) for x in dd.p.contents ]
46: desc = ''.join(desc)
47: except:
48: desc = "No description."
49: print ' <tr><td><a href="%s#%s">%s</a></td><td>%s</td></tr>' % (url, id, method, desc)
50:
51: print ''' <table>
52: </body>
53: </html>
54: '''
It uses the Beautiful Soup library to parse the manual page’s HTML and pull out the method names, the descriptions, and the links.
I have a copy of pyplot-contents.html on my local machine and it’s bookmarked in Safari. My goal is to use it to find commands as I’m learning pyplot and to edit the descriptions by hand as I go along. Eventually, I’ll have a customized table of contents (possibly reordered according to functionality instead of alphabetical position) that matches the way I use and understand the library.
You may be wondering about the matplotlib portion of Wes McKinney’s Python for Data Analysis, the book I really am going to review here sometime before the end of the year. McKinney gives a decent enough introduction to matplotlib in Chapter 8, but its purpose is more to prepare you for the plotting capabilities of his own pandas library than to work with matplotlib directly. Which is fine, but not the kind of reference I need when I’m trying to get a plot made outside of the pandas ecosystem.
Update 11/27/12
Well, that didn’t take long. Via Twitter comes this link from Tom Baldwin
Follow it and you’ll find an official matplotlib page with almost exactly the table of contents I made. So that was a waste of an hour or so.
Then comes Seth Brown with a link to a nice matplotlib tutorial.
@drdrang Try this. It’s the best reference I’ve found:
loria.fr/~rougier/teach…
— Seth Brown (@DrBunsen) Tue Nov 27 2012 9:28 PM CST
It’s not a detailed reference, but it is organized by topic instead of alphabetically.
Between the two of them, I should be able to work out almost any plotting problem I run into. Thanks, Tom and Seth!
