FIX, DOC: Bug in plot_evoked_joint API

[scott-huberty]

Fixes #13157

FYI It's a little more complicated that I thought...

The function plot_evoked_joint does have the default exclude=None, which actually does not work! 🚨 But the docstring was technically inline with the API function signature:

mne-python/mne/viz/evoked.py

Lines 1794 to 1857 in df4a3f1

	@fill_doc
	def plot_evoked_joint(
	evoked,
	times="peaks",
	title="",
	picks=None,
	exclude=None,
	show=True,
	ts_args=None,
	topomap_args=None,
	):
	"""Plot evoked data as butterfly plot and add topomaps for time points.
	.. note:: Axes to plot in can be passed by the user through ``ts_args`` or
	``topomap_args``. In that case both ``ts_args`` and
	``topomap_args`` axes have to be used. Be aware that when the
	axes are provided, their position may be slightly modified.
	Parameters
	----------
	evoked : instance of Evoked
	The evoked instance.
	times : float | array of float | "auto" | "peaks"
	The time point(s) to plot. If ``"auto"``, 5 evenly spaced topographies
	between the first and last time instant will be shown. If ``"peaks"``,
	finds time points automatically by checking for 3 local maxima in
	Global Field Power. Defaults to ``"peaks"``.
	title : str | None
	The title. If ``None``, suppress printing channel type title. If an
	empty string, a default title is created. Defaults to ''. If custom
	axes are passed make sure to set ``title=None``, otherwise some of your
	axes may be removed during placement of the title axis.
	%(picks_all)s
	exclude : None | list of str | 'bads'
	Channels names to exclude from being shown. If ``'bads'``, the
	bad channels are excluded. Defaults to ``None``.
	show : bool
	Show figure if ``True``. Defaults to ``True``.
	ts_args : None | dict
	A dict of ``kwargs`` that are forwarded to :meth:`mne.Evoked.plot` to
	style the butterfly plot. If they are not in this dict, the following
	defaults are passed: ``spatial_colors=True``, ``zorder='std'``.
	``show`` and ``exclude`` are illegal.
	If ``None``, no customizable arguments will be passed.
	Defaults to ``None``.
	topomap_args : None | dict
	A dict of ``kwargs`` that are forwarded to
	:meth:`mne.Evoked.plot_topomap` to style the topomaps.
	If it is not in this dict, ``outlines='head'`` will be passed.
	``show``, ``times``, ``colorbar`` are illegal.
	If ``None``, no customizable arguments will be passed.
	Defaults to ``None``.
	Returns
	-------
	fig : instance of matplotlib.figure.Figure | list
	The figure object containing the plot. If ``evoked`` has multiple
	channel types, a list of figures, one for each channel type, is
	returned.
	Notes
	-----
	.. versionadded:: 0.12.0
	"""

The method evoked.plot_joint has a default exclude="bads". The docstring is copied from the function plot_evoked_joint to the method evoked.plot_joint which is where the docstring-to-code discrepancy arises:

mne-python/mne/evoked.py

Lines 772 to 792 in 8f83332

	@copy_function_doc_to_method_doc(plot_evoked_joint)
	def plot_joint(
	self,
	times="peaks",
	title="",
	picks=None,
	exclude="bads",
	show=True,
	ts_args=None,
	topomap_args=None,
	):
	return plot_evoked_joint(
	self,
	times=times,
	title=title,
	picks=picks,
	exclude=exclude,
	show=show,
	ts_args=ts_args,
	topomap_args=topomap_args,
	)

TL;DR

We can update the docstring but we have to change

mne-python/mne/viz/evoked.py

Line 1800 in df4a3f1

exclude=None,

to exclude="bads"

[scott-huberty]

should we change this to something like exclude : empty list | list of str | 'bads'?

[larsoner]

I don't think so empty list is covered by list of str well enough I think

[larsoner]

Should we add a test that exclude=None raises an error? Should it?

[larsoner]

I don't think so empty list is covered by list of str well enough I think