DOC: clarify index mismatch in Epochs.drop when epochs are auto-dropped (#13688)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Thomas S. Binns <t.s.binns@outlook.com>
Co-authored-by: Daniel McCloy <dan@mccloy.info>

Author: 4 people

doc/changes/dev/13688.other.rst

@@ -0,0 +1 @@
+Add a note to :meth:`mne.Epochs.drop` describing a potential mismatch between the indices expected by :meth:`~mne.Epochs.drop` and those found in the ``selection`` attribute when epochs have been automatically dropped, by :newcontrib:`Famous Raj Bhat`.

doc/changes/names.inc

@@ -96,6 +96,7 @@
 .. _Ezequiel Mikulan: https://github.com/ezemikulan
 .. _Ezequiel Mikulan: https://github.com/ezemikulan
 .. _Fahimeh Mamashli: https://github.com/fmamashli
+.. _Famous Raj Bhat: https://github.com/Famous077
 .. _Farzin Negahbani: https://github.com/Farzin-Negahbani
 .. _Federico Raimondo: https://github.com/fraimondo
 .. _Federico Zamberlan: https://github.com/fzamberlan

mne/epochs.py

@@ -1556,6 +1556,20 @@ def drop(self, indices, reason="USER", verbose=None):
         -------
         epochs : instance of Epochs
             The epochs with indices dropped. Operates in-place.
+
+        Notes
+        -----
+        This method expects zero-based indices into the currently remaining
+        epochs, not the original event indices (as found in
+        the ``selection`` attribute). If some epochs were previously dropped (possibly
+        automatically, e.g., due to rejection thresholds or being too close to recording
+        start or end), you may need to convert indices before calling this method::
+
+            # epochs.selection contains the original indices (which are also shown by
+            # epochs.plot()) of the remaining epochs
+            plot_idx = 1  # index shown in epochs.plot()
+            drop_idx = np.where(epochs.selection == plot_idx)[0]
+            epochs.drop(drop_idx)
         """
         indices = np.atleast_1d(indices)