MRG: refactor plot_epochs_image and plot_compare_evokeds

doc/whats_new.rst

@@ -76,6 +76,22 @@ Bug
 API
 ~~~
 
+- New parameter ``clear`` in :func:`mne.viz.plot_epochs_image` for clearing pre-existing axes before plotting into them by `Daniel McCloy`_
+
+- :func:`mne.viz.plot_epochs_image` no longer supports ``group_by='type'`` — combining by channel type is now the default when ``picks`` is a channel type string; to get individual plots for each channel, pass ``picks`` as a list of channel names or indices by `Daniel McCloy`_
+
+- New parameter ``combine`` in :func:`mne.viz.plot_compare_evokeds` for specifying method to combine information across channels by `Daniel McCloy`_
+
+- The ``gfp`` parameter of :func:`mne.viz.plot_compare_evokeds` is deprecated; use ``combine='gfp'`` instead by `Daniel McCloy`_
+
+- The ``truncate_yaxis='max_ticks'`` parameter of :func:`mne.viz.plot_compare_evokeds` is deprecated; use ``truncate_yaxis='auto'`` instead by `Daniel McCloy`_
+
+- The ``truncate_xaxis`` and ``truncate_yaxis`` parameters of :func:`mne.viz.plot_compare_evokeds` now perform one-sided truncation unless both are ``True`` by `Daniel McCloy`_
+
+- The ``show_legend`` parameter of :func:`mne.viz.plot_compare_evokeds` is renamed to ``legend`` by `Daniel McCloy`_
+
+- :func:`mne.viz.plot_compare_evokeds` always returns a list of figures even when a single figure is generated by `Daniel McCloy`_
+
 - Deprecate ``average=True`` and ``spatial_colors=False`` for :func:`mne.Epochs.plot_psd` by `Jeff Hanna`_
 
 - :func:`mne.io.read_raw_brainvision` no longer raises an error when there are inconsistencies between ``info['chs']`` and ``montage`` but warns instead by `Joan Massich`_

mne/channels/layout.py

@@ -892,7 +892,7 @@ def _merge_grad_data(data, method='rms'):
     elif method == 'rms':
         data = np.sqrt(np.sum(data ** 2, axis=1) / 2)
     else:
-        raise ValueError('method must be "rms" or "mean, got %s.' % method)
+        raise ValueError('method must be "rms" or "mean", got %s.' % method)
     return data.reshape(data.shape[:1] + orig_shape[1:])
 
 

mne/epochs.py

@@ -1065,14 +1065,14 @@ def plot_image(self, picks=None, sigma=0., vmin=None, vmax=None,
                    colorbar=True, order=None, show=True, units=None,
                    scalings=None, cmap=None, fig=None, axes=None,
                    overlay_times=None, combine=None, group_by=None,
-                   evoked=True, ts_args=dict(), title=None):
+                   evoked=True, ts_args=None, title=None, clear=False):
         return plot_epochs_image(self, picks=picks, sigma=sigma, vmin=vmin,
                                  vmax=vmax, colorbar=colorbar, order=order,
                                  show=show, units=units, scalings=scalings,
                                  cmap=cmap, fig=fig, axes=axes,
                                  overlay_times=overlay_times, combine=combine,
                                  group_by=group_by, evoked=evoked,
-                                 ts_args=ts_args, title=title)
+                                 ts_args=ts_args, title=title, clear=clear)
 
     @verbose
     def drop(self, indices, reason='USER', verbose=None):

mne/tests/test_docstring_parameters.py

@@ -66,7 +66,6 @@ def get_name(func, cls=None):
 ]
 char_limit = 800  # XX eventually we should probably get this lower
 docstring_length_ignores = [
-    'mne.viz.evoked.plot_compare_evokeds::cmap',
     'mne.filter.construct_iir_filter::iir_params',
 ]
 tab_ignores = [

mne/utils/docs.py

@@ -251,6 +251,14 @@
     ``None``.
 """
 
+# Visualization
+docdict['combine'] = """
+combine : None | str | callable
+    How to combine information across channels. If a :class:`str`, must be
+    one of 'mean', 'median', 'std' (standard deviation) or 'gfp' (global
+    field power).
+"""
+
 # PSD plotting
 docdict["plot_psd_doc"] = """
 Plot the power spectral density across channels.