Repository: mne-tools/mne-python

Issue:
Documentation issue with Epochs .__getitem__
#### Describe the bug

Either the documentation for the [`Epochs.__getitem__`](https://mne.tools/stable/generated/mne.Epochs.html?highlight=selecting%20epochs#mne.Epochs.__getitem__) method is wrong, or it doesn't work as advertised because of a bug.

Specifically, point 3 from the docs:

> epochs[['name_1', 'name_2', ... ]]: Return Epochs object with a copy of the subset of epochs corresponding to multiple experimental conditions as specified by 'name_1', 'name_2', ... .

> If conditions are separated by ‘/’, selects every item containing every list tag (e.g. [‘audio’, ‘left’] selects ‘audio/left’ and ‘audio/center/left’, but not ‘audio/right’).


#### Steps to reproduce

```Python
sfreq = 100
data = np.random.randn(10, 5, sfreq*2)
info = mne.create_info(
    ch_names=['MEG1', 'MEG2', 'EEG1', 'EEG2', 'EOG'],
    ch_types=['grad', 'grad', 'eeg', 'eeg', 'eog'],
    sfreq=sfreq
)

events = np.array([
    [0, 0, 1],
    [1, 0, 2],
    [2, 0, 3],
    [3, 0, 4],
    [4, 0, 5],
    [5, 0, 6],
    [6, 0, 7],
    [7, 0, 8],
])

event_id = {
    "active/left/out1": 1,
    "active/right/out1": 2,
    "active/left/out2": 3,
    "active/right/out2": 4,
    "passive/left/out1": 5,
    "passive/right/out1": 6,
    "passive/left/out2": 7,
    "passive/right/out2": 8,
}

custom_epochs = mne.EpochsArray(data, info, events, tmin=-0.1, event_id)

# Now check
# Expected:
# active/left/out1
# active/left/out2
custom_epochs[["active", "left"]]

# but returns
 #'active/left/out1': 1
 #'active/left/out2': 1
 #'active/right/out1': 1
 #'active/right/out2': 1
 #'passive/left/out1': 1
 #'passive/left/out2': 1>

# works as expected:
custom_epochs["active/left"]
```


#### Expected results

Based on the docs I would have expected 

```
# active/left/out1
# active/left/out2
```

to be the result, see the docs:

> e.g. [‘audio’, ‘left’] selects ‘audio/left’ and ‘audio/center/left’, but not ‘audio/right’)

#### Actual results

```
 #'active/left/out1': 1
 #'active/left/out2': 1
 #'active/right/out1': 1
 #'active/right/out2': 1
 #'passive/left/out1': 1
 #'passive/left/out2': 1>
```

#### Additional information

Using MNE 0.22.1

Using `custom_epochs["active/left"]` works as expected, but is not documented.



Discussion:
This is just a documentation problem. `['a', 'b']` is like saying A or B. `['a/b']` is like saying A and B.
@drammock can you take a stab at improving the docs for this one?

Resolving patch:
diff --git a/mne/utils/mixin.py b/mne/utils/mixin.py
--- a/mne/utils/mixin.py
+++ b/mne/utils/mixin.py
@@ -92,40 +92,54 @@ def __getitem__(self, item):
         -----
         Epochs can be accessed as ``epochs[...]`` in several ways:
 
-            1. ``epochs[idx]``: Return ``Epochs`` object with a subset of
-               epochs (supports single index and python-style slicing).
-
-            2. ``epochs['name']``: Return ``Epochs`` object with a copy of the
-               subset of epochs corresponding to an experimental condition as
-               specified by 'name'.
-
-               If conditions are tagged by names separated by '/' (e.g.
-               'audio/left', 'audio/right'), and 'name' is not in itself an
-               event key, this selects every event whose condition contains
-               the 'name' tag (e.g., 'left' matches 'audio/left' and
-               'visual/left'; but not 'audio_left'). Note that tags selection
-               is insensitive to order: tags like 'auditory/left' and
-               'left/auditory' will be treated the same way when accessed.
-
-            3. ``epochs[['name_1', 'name_2', ... ]]``: Return ``Epochs`` object
-               with a copy of the subset of epochs corresponding to multiple
-               experimental conditions as specified by
-               ``'name_1', 'name_2', ...`` .
-
-               If conditions are separated by '/', selects every item
-               containing every list tag (e.g. ['audio', 'left'] selects
-               'audio/left' and 'audio/center/left', but not 'audio/right').
-
-            4. ``epochs['pandas query']``: Return ``Epochs`` object with a
-               copy of the subset of epochs (and matching metadata) that match
-               ``pandas query`` called with ``self.metadata.eval``, e.g.::
-
-                   epochs["col_a > 2 and col_b == 'foo'"]
-
-               This is only called if Pandas is installed and ``self.metadata``
-               is a :class:`pandas.DataFrame`.
-
-               .. versionadded:: 0.16
+        1. **Integer or slice:** ``epochs[idx]`` will return an `~mne.Epochs`
+           object with a subset of epochs chosen by index (supports single
+           index and Python-style slicing).
+
+        2. **String:** ``epochs['name']`` will return an `~mne.Epochs` object
+           comprising only the epochs labeled ``'name'`` (i.e., epochs created
+           around events with the label ``'name'``).
+
+           If there are no epochs labeled ``'name'`` but there are epochs
+           labeled with /-separated tags (e.g. ``'name/left'``,
+           ``'name/right'``), then ``epochs['name']`` will select the epochs
+           with labels that contain that tag (e.g., ``epochs['left']`` selects
+           epochs labeled ``'audio/left'`` and ``'visual/left'``, but not
+           ``'audio_left'``).
+
+           If multiple tags are provided *as a single string* (e.g.,
+           ``epochs['name_1/name_2']``), this selects epochs containing *all*
+           provided tags. For example, ``epochs['audio/left']`` selects
+           ``'audio/left'`` and ``'audio/quiet/left'``, but not
+           ``'audio/right'``. Note that tag-based selection is insensitive to
+           order: tags like ``'audio/left'`` and ``'left/audio'`` will be
+           treated the same way when selecting via tag.
+
+        3. **List of strings:** ``epochs[['name_1', 'name_2', ... ]]`` will
+           return an `~mne.Epochs` object comprising epochs that match *any* of
+           the provided names (i.e., the list of names is treated as an
+           inclusive-or condition). If *none* of the provided names match any
+           epoch labels, a ``KeyError`` will be raised.
+
+           If epoch labels are /-separated tags, then providing multiple tags
+           *as separate list entries* will likewise act as an inclusive-or
+           filter. For example, ``epochs[['audio', 'left']]`` would select
+           ``'audio/left'``, ``'audio/right'``, and ``'visual/left'``, but not
+           ``'visual/right'``.
+
+        4. **Pandas query:** ``epochs['pandas query']`` will return an
+           `~mne.Epochs` object with a subset of epochs (and matching
+           metadata) selected by the query called with
+           ``self.metadata.eval``, e.g.::
+
+               epochs["col_a > 2 and col_b == 'foo'"]
+
+           would return all epochs whose associated ``col_a`` metadata was
+           greater than two, and whose ``col_b`` metadata was the string 'foo'.
+           Query-based indexing only works if Pandas is installed and
+           ``self.metadata`` is a :class:`pandas.DataFrame`.
+
+           .. versionadded:: 0.16
         """
         return self._getitem(item)
 


Test patch: