Make sense of parameter "ax" in pandas.Series.plot

Question

I have following data:

After that, I execute the following codes in one cell:

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

data = pd.read_csv('examples/spx.csv', index_col=0, parse_dates=True)
spx = data['SPX']

spx.plot(ax = ax, style = 'k-')

And get the following output:

What I couldn't understand is what ax = ax in the last line is?

From pandas.Series.plot documentation, I get the following explanation for ax:

Still I couldn't understand what it is. Thank you in advance for clearing that up for me:-)

Answer 1

Note these 2 commands in your code — I displayed their relation by an arrow:

ax = fig.add_subplot(1, 1, 1)
 |
 |
 +-------------+
               |
               ↓
spx.plot(ax = ax, style = 'k-')

---

The explanation:

In the parameter ax = ax:

• The 1^st ax is the name (key) of this keyword parameter.
• The 2^nd ax is the value of this parameter.

It seems strange only because both have the same name.

If it is unpleasantly for you, you may reach the same result giving other name for your Axes object:

...
my_axes = fig.add_subplot(1, 1, 1)
...
...
spx.plot(ax=my_axes, style='k-')

(Note there are no spaces before/after = in keyword parameters — this is the recommended style for them.)

Answer 2

The ax (or Axes object) is the area of the figure where your data appears (a figure usually also contains labels, ticks, title, etc. see here).

By passing it as an argument in spx.plot(ax = ax, style = 'k-') you are basically telling pandas to plot your data on a pre-existing Axes object of your choice, instead of creating a new one (or assuming which one is the right one, as @Cameron Riddell explains in his answer).

In your case you may as well simply use:

spx.plot(style = 'k-')

if you want your data on a new Axes object.

A short example to make it clear. Suppose you create and plot two empty Axes objects:

fig, (ax1, ax2) = plt.subplots()
ax1.set_title('This is ax1')
ax2.set_title('This is ax2')
plt.plot()

If you want your data to appear on the right, then:

spx.plot(ax = ax2, style = 'k-')

Answer 3

In matplotlib you have 2 high-level objects: Figure and Axes. These objects are used to control what to plot on and where to plot. Confusingly, you can use matplotlib while ignoring these entities which gives it a "magical" feeling that the library "just knows" how/where to plot. However understanding these objects will lead to much better understanding of how matplotlib works.

• Figure: this is your area for plotting, whether it's one plot, or multiple separate plots. In colloquial terms, this is your "sheet of paper." Whether you draw one plot, or multiple plots is up to you.

• Axes: As the name implies this is a set of axes- e.g. a combination of an x-axis and y-axis. Back to our "Figure is a sheet of paper" example, a set of Axes is each one of your plots on that sheet of paper. Whether that plot has multiple different elements on it (e.g. a line plot with multiple colors or Artists) does not matter, as they are all performed on the same set of Axes.

Now that we have some definitions, in matplotlib a common coding pattern is to:

1. create a Figure (sheet of paper) with some empty Axes on it. In your case, you make a figure and then add 1 empty Axes on it called fig and ax respectively.
2. By providing a plotting function with the ax (common shorthand for Axes) argument, you're telling that plotting function to "draw" on top of your supplied axes. This is done explicitly to ensure that the plotting function will "draw" where you want it to- not to where matplotlib "assumes" you want it to.

Oftentimes, matplotlib can "assume" the correct set of Axes to draw on. However I would not rely on this, and find it to be a much better practice to explicilty create your Figure("sheet of paper") and empty Axes("plots") and tell any plotting function where you want it draw to.