matplotlib function conventions: subplots vs one figure

Question

I'm getting really confused with the subtle differences in functions (is that what they're called?) in matplotlib when working with subplots vs single figures.

As an example:

If I want to change the xlim on a single figure I'd do: plt.xlim()

If I want to change the xlim on a subplot figure I'd do: ax.set_xlim()

Why is this? Can anyone send me to a website that explains the conventions? This is an easy example because I know they're different, and how, but there are a number of ones that I don't know and I'm having trouble figuring out- for example:

1) To apply a collection to a subplot: ax.collection(collection_name). How do you do it for a single figure?

2) To apply tick labels to a subplot: ax.xaxis.ticklabels(tick_labels). How do you do this for a single figure?

Sorry this is such a newb question!

Answer 1

You are hitting the differences between the pyplot/state machine interface and the OO interface. See Which is the recommended way to plot: matplotlib or pylab? and How can I attach a pyplot function to a figure instance? for longer explainations.

For a much longer tutorial see Anatomy of Matplotlib

There is also some confusion about the layers of objects in mpl:

Important classes

Figure

The whole figure. Keeps track of all the child axes, a smattering of 'special' artists (titles, figure legends, etc), and the canvas. Don't worry too much about the canvas, it is crucial as it is the object that actually does the drawing to get you your plot, but as the user it is more-or-less invisible to you.

Axes

This is what you think of as 'a plot', it is the region of the image with the data space. It has 2 or 3 axis objects (x, y, and sometimes z), and a contains a whole bunch of artists.

Axis

These are the number line like objects. They take care of setting the graph limits and generating the ticks and tick labels. They have a Locator and a Formatter for sorting out where the ticks go and how to generate the labels

Artist

Basically everything you can see on the figure is an artist (even Figure, Axes, and Axis objects). This includes Text objects, Line2D objects, collection objects, Patch objects ... (you get the idea). When the figure is rendered, all of the artists are drawn (recursively) to the canvas. A given artist can only be in one Axes.

API layers

pylab

This is basically just a name space that a whole bunch of stuff (numpy, pyplot, mlab (ships with matplotlib)) are bulk imported into via from foo import *. This can be very convenient for interactive work, but you should not use it is scripts. The original goal of this

pyplot

This is a state machine layer that keeps track of all your open figures and has a notion of 'current figure' (plt.gcf()) and 'current axes' (plt.gca()). Most of the functions in pyplot are very thin (programitcally generated) wrappers around calls to the OO layer (plt.foo() -> plt.gca().foo() or plt.gcf().foo() depending on the function). Again, this can be convenient, but can quickly become limiting/confusing/global state causes trouble.

OO layer

This is the layer that actually manages the creation of artists (ex ax.plot(...) creates a bunch of Line2D objects). For writing scripts or anything you intend to re-use this is the layer you should try to use. To write your own plotting functions I recommend writing functions like this:

def my_plotting_fun(ax, data, data, ...):
     ax.do_stuff
     return list_of_artists_added