What does it mean when they say 'stateful'?

Question

I have a question over the matplotlib - pyplot tutorial, the link is here I'm a native dutch speaker and can read standard english. My question is not about an example that doesn't work, but about the text. In the pyplot_tutorial chapter, working with multiple figures and axis, they use the words statefulness and stateful. I don't understand what they mean. We don't have a word for it in dutch. I did a search on internet, but i didn't find anything. I think that stateful means complete, using all possibilities.

I hope that somebody has an answer for me. I know that this isn't a question to ask here because it isn't about programming, but i don't know where else to ask it.

Answer 1

In this context the difference is probably best understood by a simple plotting example.

First the stateful example:

import matplotlib.pyplot as plt

plt.figure()
plt.plot([0,1], [1,0])

Then the stateless (or rather object-oriented approach):

import matplotlib.pyplot as plt

fig = plt.figure()
ax = fig.add_subplot(111)
li = ax.plot([0,1], [1,0])

These carry out the same steps:

1. Create a figure object (matplotlib.figure.Figure)
2. Create a new plotting area object (matplotlib.axes.AxesSubplot) and add it to the figure
3. Create a new line into the plotting area (matplotlib.lines.Line2D)

In the object-oriented form we do the operations above rather explicitly and take the object references into variables (fig, ax, li). The references are not lost in the stateful interface, either, but they are hidden somewhere within matplotlib.

This difference becomes evident, when we try to change some properties, e.g. the size of the figure. With the OO approach:

fig.set_size_inches([10, 8])

With the stateful approach we first need to find the figure. There is a function for that; plt.gcf. So:

plt.gcf().set_size_inches([10,8])

is almost the same thing. The 'almost' part becomes very important in the situation where we have more than one figure open at the same time. plt.gcf returns the 'current' figure, but it is quite difficult to tell which one is the current one.

The same situation repeats with axes or lines. If we want to adjust the x ticks of the plot, then:

ax.set_xticks([0,.5,1])

is quite straightforward. With the stateful approach it becomes:

plt.gca().set_xticks([0, .5, 1])

where gca() returns the 'current' axis. If you have several subplots, this becomes quite complicated.

So, the question is who is holding the objects. The stateful interface is just a thin wrapper on the object-oriented information. All the parameters are in the objects, and there are many objects in one plot (hundreds, even thousands).

One point of the stateful interface of matplotlib is that it is often used with pylab running in IPython. This gives the stateful interface plus some shortcuts with namespaces. Plotting a sinusoid is as easy as:

x = linspace(0, 2*pi, 100)
plot(x, sin(x))

This is arguably simpler than:

import numpy as np
import matplotlib.pyplot as plt

x = np.linspace(0, 2*np.pi, 100)
fig = plt.figure()
ax = fig.add_subplot(111)
li = ax.plot(x, np.sin(x))

But while the shortcuts provided by pylab are very handy with interactive work, it is not good in scripts. I use pylab, as well, but I show almost all examples in my matplotlib related answers in th eobject-oriented form because it is much more transparent.