When to use the matplotlib.pyplot class and when to use the plot object (matplotlib.collections.PathCollection)

Question

I wondered what the logic is behind the question when to use the plot instance (which is a PathCollection) and when to use the plot class itself.

import matplotlib.pyplot as plt
p = plt.scatter([1,2,3],[1,2,3])

brings up a scatter plot. To make it work, I have to say:

plt.annotate(...)

and to configure axes labels or limits, you write:

plt.xlim(...)
plt.xlabel(...)

and so on.

But on the other hand, you write:

p.axes.set_aspect(...)
p.axes.yaxis.set_major_locator(...)

What is the logic behind this? Can I look it up somewhere? Unfortunately, I haven't found an answer to this particular question in the documentation.

When do you use the actual instance p for configuration of your graph and when do you use the pyplot class plt?

Answer 1

According to PEP20:

• "Explicit is better than implicit."
• "Simple is better than complex."

Oftentimes, the "make-it-just-work" code takes the pyplot route, as it hides away all of the figure and axes management that many wouldn't care about. This is often used for interactive mode coding, simple one-off scripts, or plotting performed at high-level scripts.

However, if you are creating a library module that is to do plotting, and you have no guarantee that the library user isn't doing any additional plotting of their own, then it is best to be explicit and avoid the pyplot interface. I usually design my functions to accept as optional arguments the axes and/or figure objects the user would like to operate upon (if not given, then I use plt.gcf() and/or plt.gca()).

The rule of thumb I have is that if the operation I am performing could be done via pyplot, but if doing so would likely change the "state machine", then I avoid pyplot. Note that any action via pyplot (such as plt.xlim()) gets/sets the current axes/figure/image (the "state machine"), while actions like ax.set_xlim() do not.

Answer 2

'plt' is just a shortcut, it's useful when you have only 1 plot. When you use the plt directly automatically matplotlib create a 'figure' and a subplot, but when you want to work with more than 1 subplot then you will need to use 'axes' methods, example:

fig = plt.figure()
a = fig.add_subplot(211)
b = fig.add_subplot(212)
print a.__class__ #<class 'matplotlib.axes.AxesSubplot'>
print fig.__class__ #<class 'matplotlib.figure.Figure'>
a.plot([0,1],[0,1],'r')
b.plot([1,0],[0,1],'b')
fig.show()

this could not be done using 'plt' directly.