Repository: mne-tools/mne-python

Issue:
Clarify the behaviour of the `events` parameter of Epochs.plot
#### Describe the new feature or enhancement
Since version 0.22 the default behaviour when plotting epochs with [`Epochs.plot()`](https://mne.tools/stable/generated/mne.Epochs.html#mne.Epochs.plot) is to not show the event labels and vertical bars at the top.
- See the graph in the [tutorial page for version 0.21](https://mne.tools/0.21/auto_tutorials/epochs/plot_10_epochs_overview.html#basic-visualization-of-epochs-objects) which used to display event info.
- See the graph in the [tutorial page for version 0.22](https://mne.tools/stable/auto_tutorials/epochs/plot_10_epochs_overview.html#basic-visualization-of-epochs-objects) and [tutorial page for dev version](https://mne.tools/dev/auto_tutorials/epochs/plot_10_epochs_overview.html#basic-visualization-of-epochs-objects) which does not display event info any more.

Maybe it would help newcomers and users used to the 0.21 behaviour to show how to do it in the tutorial?


#### Describe your proposed implementation
Replacing: `epochs.plot(n_epochs=10)` by `epochs.plot(events=epochs.events, n_epochs=10)` in [`plot_10_epochs_overview.py`](https://github.com/mne-tools/mne-python/blob/main/tutorials/epochs/plot_10_epochs_overview.py#L179).



Discussion:
I would consider it a regression, actually.  Are you up for trying a PR to fix the plotting method's default behavior, rather than editing the tutorial?  I can offer guidance as needed.
I wasn't sure if it was a bug or a feature actually 😄 

But after looking a bit into it, it seems that it was already the case before that the default for the `events` parameter of [`Epochs.plot()` in 0.21](https://github.com/mne-tools/mne-python/blob/maint/0.21/mne/epochs.py#L1064-L1077) was `None`. So I thought it may have been a bug before which have been fixed in 0.22. Do you know why it had this behaviour of displaying event info by default before with `events=None`?
Also, as we're on this, the doc says "If events are provided, the epoch numbers are not shown to prevent overlap" and "By default, the coloring scheme is the same" but it seems that epoch numbers are still shown with `events=epochs.events`. And each event has a different colour now (as opposed to [what happened in 0.21 where every vertical bar was green](https://mne.tools/0.21/auto_tutorials/epochs/plot_10_epochs_overview.html#basic-visualization-of-epochs-objects)).

Please find below the output with the following code:
```python
import os.path as op

from mne.io import read_raw_fif
from mne import read_events, Epochs


io_dir = op.join(op.dirname(__file__), 'mne', 'io')
base_dir = op.join(io_dir, 'tests', 'data')
raw_fname = op.join(base_dir, 'test_raw.fif')
eve_fname = op .join(base_dir, 'test-eve.fif')

raw = read_raw_fif(raw_fname)
epochs = Epochs(raw, read_events(eve_fname))

epochs.plot(scalings='auto', events=epochs.events, n_epochs=10, block=True)
```
![screenshot](https://user-images.githubusercontent.com/32393169/108885498-cd83a880-75ff-11eb-865e-951c2d19fa2f.png)

1. the color change was intentional, to make `raw.plot()` and `epochs.plot()` behave similarly and have similar defaults.  The old coloring can still be achieved with `event_color='g'` or so.

2. I checked and it seems like "by default the coloring scheme is the same" (between `epochs.plot()` and `mne.viz.plot_events()`) is still true (both use matplotlib default color cycle).
 
3. The docstring does seem to be inaccurate; event numbers are above and epoch numbers below so I'm not sure what "overlap" was being avoided there.

4. I hadn't noticed this before, but the "press o for options" doesn't work at all anymore.

Seems like this is a more complicated fix than it seemed at first.
I just checked out the `maint/0.21` branch and tried this "press O for options" ...  I don't think I'd ever used it before, and it actually doesn't work well at all (toggling visibility of various elements worked in the *off* direction but not when turning them back *on*, the sliders for adjusting n_channels/n_epochs both yielded IndexError...).  So, what needs to be tackled (these could be separate PRs):

1. either remove mention in docstring of "press O for options" (easy) or actually implement the options interface (hard)
2. correct inaccurate docstring statement that epoch numbers are removed when event numbers are shown

I think actually not plotting events by default is the correct behavior, since by default `events=None` so I take back what I said earlier; this is not a regression but rather 0.21 was doing something it shouldn't have :)
Okay great, will create and work on the PR when I have free time in the upcoming weeks :)

Resolving patch:
diff --git a/mne/viz/epochs.py b/mne/viz/epochs.py
--- a/mne/viz/epochs.py
+++ b/mne/viz/epochs.py
@@ -658,12 +658,10 @@ def plot_epochs(epochs, picks=None, scalings=None, n_epochs=20, n_channels=20,
     title : str | None
         The title of the window. If None, epochs name will be displayed.
         Defaults to None.
-    events : None, array, shape (n_events, 3)
-        Events to show with vertical bars. If events are provided, the epoch
-        numbers are not shown to prevent overlap. You can toggle epoch
-        numbering through options (press 'o' key). You can use
-        `~mne.viz.plot_events` as a legend for the colors. By default, the
-        coloring scheme is the same.
+    events : None | array, shape (n_events, 3)
+        Events to show with vertical bars. You can use `~mne.viz.plot_events`
+        as a legend for the colors. By default, the coloring scheme is the
+        same. Defaults to ``None``.
 
         .. warning::  If the epochs have been resampled, the events no longer
             align with the data.
diff --git a/tutorials/epochs/plot_10_epochs_overview.py b/tutorials/epochs/plot_10_epochs_overview.py
--- a/tutorials/epochs/plot_10_epochs_overview.py
+++ b/tutorials/epochs/plot_10_epochs_overview.py
@@ -173,23 +173,21 @@
 # Basic visualization of ``Epochs`` objects
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
-# The :class:`~mne.Epochs` object can be visualized (and browsed interactively)
-# using its :meth:`~mne.Epochs.plot` method:
+# The :class:`~mne.Epochs` object can be visualized with its events (and
+# browsed interactively) using its :meth:`~mne.Epochs.plot` method:
 
 epochs.plot(n_epochs=10)
 
 ###############################################################################
 # Notice that the individual epochs are sequentially numbered along the bottom
-# axis; the event ID associated with the epoch is marked on the top axis;
-# epochs are separated by vertical dashed lines; and a vertical solid green
-# line marks time=0 for each epoch (i.e., in this case, the stimulus onset
-# time for each trial). Epoch plots are interactive (similar to
-# :meth:`raw.plot() <mne.io.Raw.plot>`) and have many of the same interactive
-# controls as :class:`~mne.io.Raw` plots. Horizontal and vertical scrollbars
-# allow browsing through epochs or channels (respectively), and pressing
-# :kbd:`?` when the plot is focused will show a help screen with all the
-# available controls. See :ref:`tut-visualize-epochs` for more details (as well
-# as other ways of visualizing epoched data).
+# axis and are separated by vertical dashed lines.
+# Epoch plots are interactive (similar to :meth:`raw.plot()
+# <mne.io.Raw.plot>`) and have many of the same interactive controls as
+# :class:`~mne.io.Raw` plots. Horizontal and vertical scrollbars allow browsing
+# through epochs or channels (respectively), and pressing :kbd:`?` when the
+# plot is focused will show a help screen with all the available controls. See
+# :ref:`tut-visualize-epochs` for more details (as well as other ways of
+# visualizing epoched data).
 #
 #
 # .. _tut-section-subselect-epochs:


Test patch: