From 2f1473916f9a2286598512a7d009771646afea70 Mon Sep 17 00:00:00 2001
From: Famous <famousrajbhatt@gmail.com>
Date: Wed, 25 Feb 2026 15:32:30 +0530
Subject: [PATCH 01/10] DOC: clarify index mismatch in Epochs.drop when epochs
 are auto-dropped

---
 doc/changes/dev/11373.other.rst |  0
 mne/epochs.py                   | 15 +++++++++++++++
 2 files changed, 15 insertions(+)
 create mode 100644 doc/changes/dev/11373.other.rst

diff --git a/doc/changes/dev/11373.other.rst b/doc/changes/dev/11373.other.rst
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/mne/epochs.py b/mne/epochs.py
index 405dbc09a67..dd4880cca89 100644
--- a/mne/epochs.py
+++ b/mne/epochs.py
@@ -1540,6 +1540,21 @@ def drop(self, indices, reason="USER", verbose=None):
                   method before calling the :meth:`mne.Epochs.drop_bad` or
                   :meth:`mne.Epochs.load_data` methods.
 
+                  If some epochs were automatically dropped (e.g., due to
+                  insufficient data or rejection), the indices shown in
+                  :meth:`mne.Epochs.plot` may not match the indices expected
+                  by this method. The plot shows indices from
+                  :attr:`mne.Epochs.selection` (original event indices),
+                  while this method uses 0-based indices into the current
+                  set of remaining epochs. To convert plot indices to drop
+                  indices, use::
+
+                      # epochs.selection contains the original indices
+                      # 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)
+
         Parameters
         ----------
         indices : array of int or bool

From b8e0ec50aefef87cebda8ae86c3709f1348cb01d Mon Sep 17 00:00:00 2001
From: Famous <famousrajbhatt@gmail.com>
Date: Thu, 26 Feb 2026 11:17:36 +0530
Subject: [PATCH 02/10] DOC: clarify index mismatch in Epochs.drop when epochs
 are auto-dropped

---
 mne/epochs.py | 29 ++++++++++++++---------------
 1 file changed, 14 insertions(+), 15 deletions(-)

diff --git a/mne/epochs.py b/mne/epochs.py
index dd4880cca89..40ac4a333c2 100644
--- a/mne/epochs.py
+++ b/mne/epochs.py
@@ -1540,21 +1540,6 @@ def drop(self, indices, reason="USER", verbose=None):
                   method before calling the :meth:`mne.Epochs.drop_bad` or
                   :meth:`mne.Epochs.load_data` methods.
 
-                  If some epochs were automatically dropped (e.g., due to
-                  insufficient data or rejection), the indices shown in
-                  :meth:`mne.Epochs.plot` may not match the indices expected
-                  by this method. The plot shows indices from
-                  :attr:`mne.Epochs.selection` (original event indices),
-                  while this method uses 0-based indices into the current
-                  set of remaining epochs. To convert plot indices to drop
-                  indices, use::
-
-                      # epochs.selection contains the original indices
-                      # 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)
-
         Parameters
         ----------
         indices : array of int or bool
@@ -1571,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
+        :attr:`mne.Epochs.selection`). If some epochs were automatically
+        dropped (e.g., due to insufficient data or rejection), you may need
+        to convert indices before calling this method::
+
+            # epochs.selection contains the original indices
+            # 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)
 

From baf5553a68e6a72134b50a8076b03bde450d11d0 Mon Sep 17 00:00:00 2001
From: Famous <famousrajbhatt@gmail.com>
Date: Sat, 28 Feb 2026 23:22:55 +0530
Subject: [PATCH 03/10] DOC: rename changelog to PR number 13688 and fix
 content

---
 doc/changes/dev/11373.other.rst | 0
 doc/changes/dev/13688.other.rst | 1 +
 2 files changed, 1 insertion(+)
 delete mode 100644 doc/changes/dev/11373.other.rst
 create mode 100644 doc/changes/dev/13688.other.rst

diff --git a/doc/changes/dev/11373.other.rst b/doc/changes/dev/11373.other.rst
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/doc/changes/dev/13688.other.rst b/doc/changes/dev/13688.other.rst
new file mode 100644
index 00000000000..b8db114ca8e
--- /dev/null
+++ b/doc/changes/dev/13688.other.rst
@@ -0,0 +1 @@
+﻿Fix index mismatch in :meth:~mne.Epochs.drop when epochs are auto-dropped.
\ No newline at end of file

From fa1650ac36d849c3edbabd66ce84fe3ecacedbbd Mon Sep 17 00:00:00 2001
From: Famous <famousrajbhatt@gmail.com>
Date: Sun, 1 Mar 2026 01:37:40 +0530
Subject: [PATCH 04/10] DOC: update changelog wording and add contributor name

---
 doc/changes/dev/13688.other.rst | 2 +-
 doc/changes/names.inc           | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/changes/dev/13688.other.rst b/doc/changes/dev/13688.other.rst
index b8db114ca8e..d734e18c5df 100644
--- a/doc/changes/dev/13688.other.rst
+++ b/doc/changes/dev/13688.other.rst
@@ -1 +1 @@
-﻿Fix index mismatch in :meth:~mne.Epochs.drop when epochs are auto-dropped.
\ No newline at end of file
+Add a note to :meth:`~mne.Epochs.drop` describing a potential mismatch between indices expected by :meth:`~mne.Epochs.drop` and those found in :attr:`~mne.Epochs.selection` when epochs have been automatically dropped, by :newcontrib:`Famous Raj Bhat`.
\ No newline at end of file
diff --git a/doc/changes/names.inc b/doc/changes/names.inc
index 09c5818b6af..400a14e08e5 100644
--- a/doc/changes/names.inc
+++ b/doc/changes/names.inc
@@ -364,3 +364,5 @@
 .. _Zhi Zhang: https://github.com/tczhangzhi/
 .. _Ziyi ZENG: https://github.com/ZiyiTsang
 .. _Zvi Baratz: https://github.com/ZviBaratz
+
+.. _Famous Raj Bhat: https://github.com/Famous077

From b9a1fa7e6467fd1fc0d14a7f9658f074e6474fcb Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sat, 28 Feb 2026 20:08:05 +0000
Subject: [PATCH 05/10] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 doc/changes/names.inc | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/doc/changes/names.inc b/doc/changes/names.inc
index 400a14e08e5..c6b4b00c499 100644
--- a/doc/changes/names.inc
+++ b/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
@@ -364,5 +365,3 @@
 .. _Zhi Zhang: https://github.com/tczhangzhi/
 .. _Ziyi ZENG: https://github.com/ZiyiTsang
 .. _Zvi Baratz: https://github.com/ZviBaratz
-
-.. _Famous Raj Bhat: https://github.com/Famous077

From 7eae28cc08e2165a21524a37e65074143c4bdbc7 Mon Sep 17 00:00:00 2001
From: "Thomas S. Binns" <t.s.binns@outlook.com>
Date: Sun, 1 Mar 2026 20:58:57 +0000
Subject: [PATCH 06/10] build docs [skip azp][skip actions]


From 044f0fd50792373e5398609da9d3281c863cb23b Mon Sep 17 00:00:00 2001
From: "Thomas S. Binns" <t.s.binns@outlook.com>
Date: Tue, 3 Mar 2026 17:14:00 +0000
Subject: [PATCH 07/10] build docs [skip azp][skip actions]


From 7d3ce7f88c97ab2bc5803c391579d306eef07511 Mon Sep 17 00:00:00 2001
From: Famous <famousrajbhatt@gmail.com>
Date: Wed, 4 Mar 2026 23:41:14 +0530
Subject: [PATCH 08/10] DOC: replace :attr: cross-reference with plain text for
 selection attribute

---
 doc/changes/dev/13688.other.rst | 2 +-
 mne/epochs.py                   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/changes/dev/13688.other.rst b/doc/changes/dev/13688.other.rst
index d734e18c5df..c707eb61393 100644
--- a/doc/changes/dev/13688.other.rst
+++ b/doc/changes/dev/13688.other.rst
@@ -1 +1 @@
-Add a note to :meth:`~mne.Epochs.drop` describing a potential mismatch between indices expected by :meth:`~mne.Epochs.drop` and those found in :attr:`~mne.Epochs.selection` when epochs have been automatically dropped, by :newcontrib:`Famous Raj Bhat`.
\ No newline at end of file
+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`.
\ No newline at end of file
diff --git a/mne/epochs.py b/mne/epochs.py
index 40ac4a333c2..894a4f406b2 100644
--- a/mne/epochs.py
+++ b/mne/epochs.py
@@ -1561,7 +1561,7 @@ def drop(self, indices, reason="USER", verbose=None):
         -----
         This method expects zero-based indices into the currently remaining
         epochs, not the original event indices (as found in
-        :attr:`mne.Epochs.selection`). If some epochs were automatically
+        the ``selection`` attribute). If some epochs were automatically
         dropped (e.g., due to insufficient data or rejection), you may need
         to convert indices before calling this method::
 

From 7a3835ce47c24b950c837698c065e4621982398d Mon Sep 17 00:00:00 2001
From: Famous <famousrajbhatt@gmail.com>
Date: Wed, 4 Mar 2026 23:50:47 +0530
Subject: [PATCH 09/10] DOC: remove tilde from first meth reference in
 changelog

---
 doc/changes/dev/13688.other.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/changes/dev/13688.other.rst b/doc/changes/dev/13688.other.rst
index c707eb61393..c061900d78a 100644
--- a/doc/changes/dev/13688.other.rst
+++ b/doc/changes/dev/13688.other.rst
@@ -1 +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`.
\ No newline at end of file
+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`.
\ No newline at end of file

From 31982bac310582a6227a8e42e2dcfb96bf40b0c9 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Wed, 4 Mar 2026 15:57:00 -0600
Subject: [PATCH 10/10] Apply suggestions from code review

---
 mne/epochs.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/mne/epochs.py b/mne/epochs.py
index 894a4f406b2..c9600a0650f 100644
--- a/mne/epochs.py
+++ b/mne/epochs.py
@@ -1561,12 +1561,12 @@ def drop(self, indices, reason="USER", verbose=None):
         -----
         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 automatically
-        dropped (e.g., due to insufficient data or rejection), you may need
-        to convert indices before calling this method::
+        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
-            # of the remaining epochs
+            # 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)
