Hierarchy in matplotlib

Question

According to this article, everything in matplotlib is organized in a hierarchy. At the top of the hierarchy is the matplotlib "state-machine environment" which is provided by the matplotlib.pyplot module. At this level, simple functions are used to add plot elements (lines, images, text, etc.) to the current axes in the current figure. The next level down in the hierarchy is the first level of the object-oriented interface, in which pyplot is used only for a few functions such as figure creation, and the user explicitly creates and keeps track of the figure and axes objects. At this level, the user uses pyplot to create figures, and through those figures, one or more axes objects can be created. These axes objects are then used for most plotting actions. There are also other terms like Figure, Axes, Axis, Artist (there is nice picture which explains all of those, on mentioned page). In summary:

1. Everything belongs to matplotlib.pyplot module
2. Figure - keeps track of all the child Axes, a smattering of ‘special’ artists (titles, figure legends, etc)
3. Axes - region of the image with the data space - belongs to Figure
4. Axis - strings labeling the ticks (x,y,z coordinates etc) - belongs to Axes
5. Artist - everything you can see on the figure (even the Figure, Axes, and Axis objects) - belongs to Figure

The easiest way to create a new figure is with pyplot:

fig = plt.figure()  # an empty figure with no axes
fig, ax_lst = plt.subplots(2, 2)  # a figure with a 2x2 grid of Axes

I've often seen those two approaches used interchangeably, and I hoped they are basically equivalents. But I cannot achieve same result using the fig, ax = plt.subplots() as I get using the fig = plt.figure() and ax = fig.add_subplot(111, projection='3d')

Here are my experiments, for plt.figure():

In [1]: from mpl_toolkits.mplot3d import Axes3D

In [2]: import matplotlib.pyplot as plt

In [3]: fig = plt.figure()

In [4]: ax = fig.add_subplot(111, projection='3d')

In [5]: fig
Out[5]: <matplotlib.figure.Figure at 0x7f8377ca0610>

In [6]: ax
Out[6]: <matplotlib.axes._subplots.Axes3DSubplot at 0x7f8377bfb310>

In [7]: 

Here are my experiments, for plt.subplots():

In [1]: from mpl_toolkits.mplot3d import Axes3D

In [2]: import matplotlib.pyplot as plt

In [3]: fig, ax = plt.subplots()

In [4]: fig
Out[4]: <matplotlib.figure.Figure at 0x7f3dcf96e710>

In [5]: ax
Out[5]: <matplotlib.axes._subplots.AxesSubplot at 0x7f3dced564d0>

In [6]: 

As you can see the first creates the matplotlib.axes._subplots.Axes3DSubplot object while the second creates matplotlib.axes._subplots.AxesSubplot object. I've been searching through help(plt.subplots) for projection keyword but I did not find anything. So I've tried to use same arguments for plt.subplots as for fig.add_subplot but I get the following error:

In [7]: fig, ax = plt.subplots(111, projection='3d')
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
<ipython-input-7-a905adad48f5> in <module>()
----> 1 fig, ax = plt.subplots(111, projection='3d')

/usr/lib/python2.7/dist-packages/matplotlib/pyplot.pyc in subplots(nrows, ncols, sharex, sharey, squeeze, subplot_kw, gridspec_kw, **fig_kw)
   1076         gridspec_kw = {}
   1077 
-> 1078     fig = figure(**fig_kw)
   1079     gs = GridSpec(nrows, ncols, **gridspec_kw)
   1080 

/usr/lib/python2.7/dist-packages/matplotlib/pyplot.pyc in figure(num, figsize, dpi, facecolor, edgecolor, frameon, FigureClass, **kwargs)
    433                                         frameon=frameon,
    434                                         FigureClass=FigureClass,
--> 435                                         **kwargs)
    436 
    437         if figLabel:

/usr/lib/python2.7/dist-packages/matplotlib/backends/backend_tkagg.pyc in new_figure_manager(num, *args, **kwargs)
     78     """
     79     FigureClass = kwargs.pop('FigureClass', Figure)
---> 80     figure = FigureClass(*args, **kwargs)
     81     return new_figure_manager_given_figure(num, figure)
     82 

TypeError: __init__() got an unexpected keyword argument 'projection'

Question:

Are fig, ax = plt.subplots() and fig = plt.figure(); ax = fig.add_subplot(111, projection='3d') equivalents, if yes how can I use fig, ax = plt.subplots() in my example?

On the mentioned page there is also following code:

#!/bin/env python

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 2, 100)

# The first call to plt.plot will automatically create the necessary figure and axes to achieve the desired plot.
plt.plot(x, x, label='linear')

# Subsequent calls to plt.plot re-use the current axes and each add another line.
plt.plot(x, x**2, label='quadratic')
plt.plot(x, x**3, label='cubic')

# Setting the title, legend, and axis labels also automatically use the current axes and set the title, create the legend, and label the axis respectively.
plt.xlabel('x label')
plt.ylabel('y label')

plt.title("Simple Plot")

plt.legend()

plt.show()

As you can see there are no such functions fig = plt.figure() nor fig, ax_lst = plt.subplots(2, 2)

Question:

How is the hierarchy maintained in this example, is Figure created by default or what is going on?

Answer 1

Question 1

I think you've shown for yourself that the commands are not wholly equivalent and just want some reassurance of this.

To do what you want to do - you can pass in projection to the add_subplot() calls that are used 'under the covers' by setting up a dictionary of subplot arguments and passing them in e.g.

from mpl_toolkits.mplot3d import Axes3D
import matplotlib.pyplot as plt
subplot_args = {'projection':'3d'}
fig, ax = plt.subplots(subplot_kw=subplot_args)

The use of the named argument subplot_kw is described in the docs here.

Question 2

The figure axes etc are all created 'under the covers' by the first line beginning plt.plot. The pyplot module is maintaining state and reusing the same figure instance and axes instance until you call plt.show().

Note - as it stands you don't have a handle to these instances. You can always get a handle if you want e.g. by calling

fig = plt.gcf()

and

ax = plt.gca()

where gcf() and gca() are get current figure and get current axes respectively. This is modelled on the matlab functionality upon which matplotlib was originally based.

If you're really keen to see how the auto creation is done - it's all open source. You can see the call to plot() creates an Axes instance by a call to gca() in the code here. This in turn calls gcf(), which looks for a FigureManager (which is what actually maintains the state). If one exists, it returns the figure it's managing, otherwise it creates a new one using plt.figure(). Again, this process to some degree inherits from matlab, where the initial call is usually figure before any plotting operation.

---

Addendum

I think what you might be driving at is how use of the matplotlib.pyplot functions like plt.plot() etc give you access to the hierarchy as described by the documentation. The answer is that if you want really fine grained control, it sometimes doesn't. That's why people use the

fig, ax = plt.subplots()

pattern or similar so that they have handles to the figure and axes objects directly and can manipulate them as they like.