[DISCUSSION] Showing figures when running in non-interactive python: to block or not to block?

[wmvanvliet]

@Gnefil pointed out an interesting inconsistency when we are making figures in plain python mode, i.e. when running a script containing visualizations with python myscript.py from the terminal (no ipython or jupyter or anything). The behavior of when a figure window is "blocking" or not is inconsistent among different figure types.

For a concrete example, say we start out script by loading in the evokeds from the MNE-Sample dataset:

import mne
data_path = mne.datasets.sample.data_path()
evokeds_fname = data_path / "MEG" / "sample" / "sample_audvis-ave.fif"
evoked = mne.read_evokeds(evokeds_fname, condition="Left Auditory")

If we continue the script with a topomap figure:

evoked.plot_topomap()

The script will briefly open a window to draw the figure and then close it immediately as the python script terminates. However, if we make it a different kind of plot:

evoked.plot_topo()

The figure window opens and the script blocks execution until the user manually closes the window. If this is not desired, you can disable opening the window entirely with evoked.plot_topo(show=False).

Puzzled by this, I did a search through the codebase on our default blocking behavior and found this:

C:\Users\wmvan\projects\mne-python\mne main
> ag 'plt_show\('
decoding\spatial_filter.py
638:        plt_show(show, block=False)

preprocessing\eyetracking\calibration.py
191:        plt_show(show)

time_frequency\spectrum.py
712:        plt_show(show, fig)
776:        plt_show(show, block=block)

time_frequency\tfr.py
1671:            plt_show(fig=fig)
2171:        plt_show(show)
2467:        plt_show(show)
2598:        plt_show(show)

viz\circle.py
392:    plt_show(show)

viz\epochs.py
402:    plt_show(show)
649:    plt_show(show, fig=fig)
736:    plt_show(show)

viz\evoked.py
207:    plt_show()
569:    plt_show(show)
1734:    plt_show(show)
1794:    plt_show(show)
2071:    plt_show(show)
3230:    plt_show(show)

viz\eyetracking\heatmap.py
208:    plt_show(show)

viz\misc.py
255:    plt_show(show)
374:    plt_show(show)
613:        plt_show(show, fig=fig)
959:    plt_show(show)
1311:    plt_show(show)
1425:    plt_show(show)
1575:    plt_show(show)

viz\ica.py
660:    plt_show(show)
912:    plt_show(show)
1040:    plt_show(show)
1227:    plt_show(show)
1271:    plt_show(show)

viz\_3d.py
410:    plt_show(show)
2303:    plt_show(True)
3236:    plt_show(show)
3656:    plt_show(show)
3993:    plt_show(show, block=block)

viz\utils.py
130:def plt_show(show=True, fig=None, **kwargs):
185:        plt_show(show, block=block, **kwargs)
534:        plt_show(fig=fig_proj, warn=False)
673:            plt_show(fig=fig_help, warn=False)
724:        plt_show(block=True)
762:        plt_show()
1331:    plt_show(show, block=block)

viz\_dipole.py
188:    plt_show(show, block=block)

viz\_proj.py
250:    plt_show(show)

viz\_mpl_figure.py
978:        plt_show(fig=fig)
1042:            plt_show(fig=self.mne.fig_help)
1199:        plt_show(fig=fig)
1767:        plt_show(fig=self.mne.fig_proj, warn=False)

viz\topo.py
423:        plt_show(fig=fig)
1171:    plt_show(show)
1355:    plt_show(show)

viz\topomap.py
524:    plt_show(show)
1485:    plt_show(show)
1881:    plt_show(show)
2111:    plt_show(show)
2282:    plt_show(show, block=False)
3109:        plt_show(show)
3159:    plt_show(show)
3249:    plt_show(True)
3485:    plt_show(show, block=False)
3609:    plt_show(show)
3792:    plt_show(show)
4257:    plt_show(show)

The default matplotlib behavior is to have block=True for plt.show() when in non-interactive mode. But for some reason, we override this setting for some of our plots. We also expose and document the block parameter for our non-matplotlib figures, whereas we don't do this for the matplotlib figures, but that is perhaps besides the point.

Should the hardcoded block=False should be removed from our matplotlib figures that do this? Or is there a good reason why some figures have this?

[Gnefil]

This issue may be relevant to bug #13956.

[cbrnr]

I think the inconsistency is even earlier. Whereas Matplotlib doesn't show a figure unless users explicitly call plt.show() (which is blocking in the default non-interactive mode), MNE figures show automatically (i.e., they call plt.show()). Users can control this behavior with the show argument (which by default is True, in contrast to Matplotlib, where e.g. plt.plot() does not show automatically). IMO we could make the MNE behavior more explicit by adding a block argument and set a consistent default. By exposing block in addition to show, individual functions could also set different defaults if that makes more sense, but then users could at least understand the behavior.

[wmvanvliet]

Why did we add show=True again? There must be been a good reason 🤔 In an interactive non-blocking environment, figures will show always regardless of what you set plot to, so I guess it must have been for people in a regular python REPL being confused why their figures would not show?

[cbrnr]

I don't know, maybe this was the reason, but I find that much more confusing since it does not behave like Matplotlib. By "interactive non-blocking environment" I assume you are referring to Jupyter notebooks?

[wmvanvliet]

Those, or just plain old ipython

[cbrnr]

AFAIK plain IPython behaves exactly like the default Python REPL, i.e., interactive mode is off. You have to explicitly enable it with %matplotlib (see here). In the Python REPL you have to import matplotlib.pyplot as plt followed by plt.ion() to achieve the same thing. So in both cases, figures do not pop up automatically.

[wmvanvliet]

ah you're right

[cbrnr]

But yeah, I thought about it some more, since all plotting functions have a show argument, we can already influence if a figure is shown automatically (the default) or if we want to show them explicitly later with plt.show(). So I agree that we should fix the behavior of those functions that hardcode block=True unless there are good reasons why they are doing that.