MRG, VIZ, MAINT: Use new figure class for epochs.plot and ICA.plot_so…

…urces (#8381)

* use figure class for ICA and Epochs viz...

show ICA properties on right-click of component name

renable right-click on ch name

fix EOG scaling

better pageup behavior when at bottom of channel list

disable butterfly for ICA

better keypress testing

travis old deps debugging

refactor plot_properties integration

make bads color consistent with plot_raw

fix _fake_click location to work when MNE_BROWSE_RAW_SIZE not set

touch tutorial

update what's new

remove unreachable condition

persist changes to ICA exclude

WIP: handle epochs too

take advantage of numpy version bump

fix ticks

fix scrolling

click to mark bad; refactor

allow bad epoch marking

fix instructions

get vlines working

add image plot on right-click

add epoch histogram

bad ch color trumps bad epoch color

use plt_show for epochs

support custom colors for (autoreject compatibility)

snap to epoch boundaries when clicking scrollbar

verbose=False on channel/component context click figures

make it work for ica.plot_sources(epochs)

touch epochs tutorial

fix CIs (disable keypress j if no projs present)

clean up help window code

make "show histogram" key a toggle

retain xlabel in zen mode

* closes #4850

* docstring, codespell, whitespace, coverage

fix: make epoch_colors work in butterfly mode

* closes #8304

* ENH: Add butterfly

* fix tests

update what's new

Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

doc/changes/latest.inc

@@ -55,6 +55,7 @@ Enhancements
 
 - Further improved documentation building instructions and execution on Windows (:gh:`8502` by `kalenkovich`_ and `Eric Larson`_)
 
+- `mne.preprocessing.ICA.plot_sources` now displays an `mne.preprocessing.ICA.plot_properties` window when right-clicking on component names on the y-axis (:gh:`8381` by `Daniel McCloy`_)
 
 
 Bugs
@@ -139,3 +140,7 @@ API changes
 - New `mne.viz.Brain.set_time` method to set the displayed time in seconds (:gh:`8415` by `Daniel McCloy`_)
 
 - Update the ``backend`` parameter of :func:`mne.viz.plot_source_estimates` to integrate ``pyvista`` (:gh:`8395` by `Guillaume Favelier`_)
+
+- Add ``group_by`` parameter to `mne.viz.plot_epochs` and `mne.Epochs.plot` to allow displaying channel data by sensor position (:gh:`8381` by `Daniel McCloy`_)
+
+- Parameter ``event_colors`` in `mne.viz.plot_epochs` and `mne.Epochs.plot` is deprecated, replaced by ``event_color`` which is consistent with `mne.viz.plot_raw` and provides greater flexibility (:gh:`8381` by `Daniel McCloy`_)

mne/epochs.py

@@ -1095,18 +1095,28 @@ def ch_names(self):
 
     @copy_function_doc_to_method_doc(plot_epochs)
     def plot(self, picks=None, scalings=None, n_epochs=20, n_channels=20,
-             title=None, events=None, event_colors=None, order=None,
-             show=True, block=False, decim='auto', noise_cov=None,
+             title=None, events=None, event_colors=None, event_color=None,
+             order=None, show=True, block=False, decim='auto', noise_cov=None,
              butterfly=False, show_scrollbars=True, epoch_colors=None,
-             event_id=None):
+             event_id=None, group_by='type'):
+        if event_colors is not None:
+            depr_msg = ('event_colors is deprecated and will be replaced by '
+                        'event_color in 0.23.')
+            if event_color is None:
+                event_color = event_colors
+            else:
+                depr_msg += (' Since you passed values for both event_colors '
+                             'and event_color, event_colors will be ignored.')
+            warn(depr_msg, DeprecationWarning)
         return plot_epochs(self, picks=picks, scalings=scalings,
                            n_epochs=n_epochs, n_channels=n_channels,
-                           title=title, events=events,
+                           title=title, events=events, event_color=event_color,
                            event_colors=event_colors, order=order,
                            show=show, block=block, decim=decim,
                            noise_cov=noise_cov, butterfly=butterfly,
                            show_scrollbars=show_scrollbars,
-                           epoch_colors=epoch_colors, event_id=event_id)
+                           epoch_colors=epoch_colors, event_id=event_id,
+                           group_by=group_by)
 
     @copy_function_doc_to_method_doc(plot_epochs_psd)
     def plot_psd(self, fmin=0, fmax=np.inf, tmin=None, tmax=None,

mne/utils/__init__.py

@@ -47,7 +47,8 @@
                        requires_neuromag2ft, requires_pylsl, assert_object_equal,
                        assert_and_remove_boundary_annot, _raw_annot,
                        assert_dig_allclose, assert_meg_snr, assert_snr,
-                       assert_stcs_equal, modified_env)
+                       assert_stcs_equal, modified_env, _click_ch_name,
+                       _close_event)
 from .numerics import (hashfunc, _compute_row_norms,
                        _reg_pinv, random_permutation, _reject_data_segments,
                        compute_corr, _get_inst_data, array_split_idx,

mne/utils/_testing.py

@@ -519,3 +519,23 @@ def modified_env(**d):
                 os.environ[key] = val
             elif key in os.environ:
                 del os.environ[key]
+
+
+def _click_ch_name(fig, ch_index=0, button=1):
+    """Click on a channel name in a raw/epochs/ICA browse-style plot."""
+    from ..viz.utils import _fake_click
+    fig.canvas.draw()
+    x, y = fig.mne.ax_main.get_yticklabels()[ch_index].get_position()
+    xrange = np.diff(fig.mne.ax_main.get_xlim())[0]
+    _fake_click(fig, fig.mne.ax_main, (x - xrange / 50, y),
+                xform='data', button=button)
+
+
+def _close_event(fig):
+    """Force calling of the MPL figure close event."""
+    # XXX workaround: plt.close() doesn't spawn close_event on Agg backend
+    # (check MPL github issue #18609; scheduled to be fixed by MPL 3.4)
+    try:
+        fig.canvas.close_event()
+    except ValueError:  # old mpl with Qt
+        pass  # pragma: no cover

mne/utils/docs.py

@@ -95,6 +95,29 @@
     channel names in the file will be used when possible.
 """
 
+docdict['event_color'] = """
+event_color : color object | dict | None
+    Color(s) to use for events. To show all events in the same color, pass any
+    matplotlib-compatible color. To color events differently, pass a `dict`
+    that maps event names or integer event numbers to colors (must include
+    entries for *all* events, or include a "fallback" entry with key ``-1``).
+    If ``None``, colors are chosen from the current Matplotlib color cycle.
+"""
+
+docdict['browse_group_by'] = """
+group_by : str
+    How to group channels. ``'type'`` groups by channel type,
+    ``'original'`` plots in the order of ch_names, ``'selection'`` uses
+    Elekta's channel groupings (only works for Neuromag data),
+    ``'position'`` groups the channels by the positions of the sensors.
+    ``'selection'`` and ``'position'`` modes allow custom selections by
+    using a lasso selector on the topomap. In butterfly mode, ``'type'``
+    and ``'original'`` group the channels by type, whereas ``'selection'``
+    and ``'position'`` use regional grouping. ``'type'`` and ``'original'``
+    modes are ignored when ``order`` is not ``None``. Defaults to ``'type'``.
+"""
+
+
 # Epochs
 docdict['proj_epochs'] = """
 proj : bool | 'delayed'

mne/viz/__init__.py

@@ -25,7 +25,7 @@
                      plot_epochs_image)
 from .raw import plot_raw, plot_raw_psd, plot_raw_psd_topo, _RAW_CLIP_DEF
 from .ica import (plot_ica_scores, plot_ica_sources, plot_ica_overlay,
-                  _plot_sources_raw, _plot_sources_epochs, plot_ica_properties)
+                  _plot_sources, plot_ica_properties)
 from .montage import plot_montage
 from .backends.renderer import (set_3d_backend, get_3d_backend, use_3d_backend,
                                 set_3d_view, set_3d_title, create_3d_figure,