Add `clf` kwarg to plt.figure() #7023

DietBru · 2016-09-04T20:53:02Z

Adds the keyword clf=False to plt.figure(). It clears the content of an already existing figure (being referenced by the num kwarg).

The original motivation is stated in #6285. Another view would be: Instead of writing
fg = plt.figure(num=10); fg.clf(), one can write fg = plt.figure(num=10, clf=True). The clf() is needed when the script is called repeatedly (with different parameters) in an interactive interpreter.

The discussion if this is api bloat or not can be continued here. From a user perspective, it changes

fg = plt.figure(num=10)
fg.clf()
fg, axx = plt.subplots(3, 3, num=10)

to

fg, axx = plt.subplots(3, 3, num=10, clf=True)

which is imho much more readable.
Closes #6285.

efiring · 2016-09-04T21:44:33Z

lib/matplotlib/pyplot.py

@@ -557,6 +564,9 @@ def make_active(event):
        if _INSTALL_FIG_OBSERVER:
            fig.stale_callback = _auto_draw_if_interactive

+    if clf and len(figManager.canvas.figure.axes) > 0:
+        figManager.canvas.figure.clear()


Without committing myself yet as to whether the PR as a whole is a good idea, I think that the clearing should be unconditional, not based on whether there are axes objects. Otherwise, it is only a partial clearing of the figure.

tacaswell · 2016-09-04T21:53:32Z

I thought the suggestion was to put this flag on Figure.subplots.

efiring · 2016-09-04T22:06:32Z

There is a potentially reasonable justification for it only in subplots, but putting it in figure automatically puts it in subplots, and makes the two more consistent. It also keeps everything at the pyplot level only, which could be viewed as good (don't make the library level more complicated) or bad (better to keep the pyplot level as consistent with the library level as possible).
I don't think it belongs at the library level because to me, Figure.subplots should be making a fresh array of subplots, period. Similarly, Figure.add_subplot should add a subplot, not return an existing one. Adding this 'clear' kwarg at the Figure level would make it more awkward to deprecate and remove the peculiar part of the add_subplot behavior.

anntzer · 2016-09-07T05:06:56Z

Note that as of 2.1 you can already write

fig = plt.figure(...); fig.clf()
axs = fig.subplots(...)

Actually, thinking about it again, it's not even clear why you'd want to reuse a figure. Can't you just close whatever figure you don't care about and create a new one?
Plus, I'd say getting figures by their num is so MATLAB-ish; you could just keep a reference to the figure itself.
Anyways, still -1.

efiring · 2016-09-07T06:36:05Z

On 2016/09/06 7:06 PM, Antony Lee wrote:

Actually, thinking about it again, it's not even clear why you'd want to
reuse a figure. Can't you just close whatever figure you don't care
about and create a new one?

No, that's not at all the point. Suppose you want to cycle through
plots of a given type. You make a figure, and position and resize it on
the screen. You want to be able to leave it there while running your
script--you don't want a new one flashing up each time.

efiring · 2016-09-07T06:43:51Z

On 2016/09/06 7:06 PM, Antony Lee wrote:

Plus, I'd say getting figures by their |num| is so MATLAB-ish; you could
just keep a reference to the figure itself.

Yes, but with mpl one can also use a name in place of the number; and
the point of the pyplot interface is to make it easy for people to
transition from Matlab, and to do a quick style of interactive
computing. (I agree in preferring the approach of keeping a reference
to the figure and then calling its subplots method; maybe the addition
of that method does tip the balance away from adding the clean kwarg.)

anntzer · 2016-09-07T06:58:29Z

No, that's not at all the point. Suppose you want to cycle through
plots of a given type. You make a figure, and position and resize it on
the screen. You want to be able to leave it there while running your
script--you don't want a new one flashing up each time.

Good point, didn't think about this use.

tacaswell · 2016-09-24T19:42:34Z

I actually use the plt.figure('some name') at my day-job as part of beamline control system to manage over plotting in a reasonable way. Sometimes global state is the right answer (as painful as it is for me to type that 😜 ) and it is handy that mpl takes care of some of that state management for you.

tacaswell · 2016-09-24T19:43:11Z

lib/matplotlib/pyplot.py

@@ -429,6 +429,7 @@ def figure(num=None,  # autoincrement if None, else integer from 1-N
           facecolor=None,  # defaults to rc figure.facecolor
           edgecolor=None,  # defaults to rc figure.edgecolor
           frameon=True,
+           clear=False,


This needs to be the last arg to maintain back compatibility.

tacaswell · 2016-09-24T19:44:56Z

lib/matplotlib/pyplot.py

@@ -557,6 +564,9 @@ def make_active(event):
        if _INSTALL_FIG_OBSERVER:
            fig.stale_callback = _auto_draw_if_interactive

+    if clear:
+        figManager.canvas.figure.clear()


🚲 🏠 fig is a ref to the current figure that we already have just above.

The fig ref only exists if in Line 520 if figManager is None.

tacaswell · 2016-09-24T19:50:08Z

I am mostly convinced by @efiring that this should stay in pyplot and not be moved back into the object layer.

@vollbier Can you please add a 'whats_new' entry with examples of both plt.figure and plt.subplots?

codecov-io · 2016-12-26T10:21:14Z

Current coverage is 62.07% (diff: 100%)

Merging #7023 into master will increase coverage by <.01%

@@             master      #7023   diff @@
==========================================
  Files           174        174          
  Lines         56021      56023     +2   
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
+ Hits          34773      34776     +3   
+ Misses        21248      21247     -1   
  Partials          0          0

Powered by Codecov. Last update ab98852...e249ac3

tacaswell · 2016-12-27T02:49:19Z

Can you rebase this to and squash it to 1 or 2 commits? See http://matplotlib.org/devdocs/devel/gitwash/development_workflow.html#rebasing-a-pull-request-pr

This needs a minimal test, using @cleanup and the examples in the whats-new would be perfect (and is an obvious candidate for a pytest paramterized test.

docs were added

QuLogic · 2016-12-27T03:02:30Z