From b8cb797547a453d09949ec0beed10fb80646e89d Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Wed, 8 Apr 2026 15:49:44 +0530 Subject: [PATCH 01/17] DOC: Clarify add_reference_channels usage with average reference --- mne/channels/channels.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/mne/channels/channels.py b/mne/channels/channels.py index c1a3d462525..002b4d42a73 100644 --- a/mne/channels/channels.py +++ b/mne/channels/channels.py @@ -812,6 +812,12 @@ def add_reference_channels(self, ref_channels): ------- inst : same type as the input data The modified instance. + + note:: If you are adding a new reference channel to data that + will eventually be used with an average reference, + you should also call :meth:`mne.io.Raw.set_eeg_reference` + (or the equivalent Epochs/Evoked method) to ensure the + mathematical reference is updated correctly. """ return add_reference_channels(self, ref_channels, copy=False) From e270d35644946145e64bf2aafdd2eca3fa7e013f Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Thu, 16 Apr 2026 19:31:06 +0530 Subject: [PATCH 02/17] DOC: take over #13664 to clarify avg behavior and add towncrier --- doc/changes/dev/13618.notable.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changes/dev/13618.notable.rst diff --git a/doc/changes/dev/13618.notable.rst b/doc/changes/dev/13618.notable.rst new file mode 100644 index 00000000000..10202f8c55a --- /dev/null +++ b/doc/changes/dev/13618.notable.rst @@ -0,0 +1 @@ +Clarify average EEG reference behavior in documentation for add_reference_channels. \ No newline at end of file From 5ecd0c029eb57886cb60435b3e55fa94c4021e9d Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 16 Apr 2026 14:15:35 +0000 Subject: [PATCH 03/17] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- mne/channels/channels.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mne/channels/channels.py b/mne/channels/channels.py index 002b4d42a73..c8ee5f74d57 100644 --- a/mne/channels/channels.py +++ b/mne/channels/channels.py @@ -812,7 +812,7 @@ def add_reference_channels(self, ref_channels): ------- inst : same type as the input data The modified instance. - + note:: If you are adding a new reference channel to data that will eventually be used with an average reference, you should also call :meth:`mne.io.Raw.set_eeg_reference` From e110c7c096209ce9c4f60424392f22b5e8ffedf9 Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Wed, 22 Apr 2026 10:10:15 +0530 Subject: [PATCH 04/17] DOC: move and reformat avg ref note --- mne/utils/docs.py | 5 +++++ tutorials/preprocessing/55_setting_eeg_reference.py | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/mne/utils/docs.py b/mne/utils/docs.py index fc7d33a6f4b..c10d0d9a3bf 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4103,6 +4103,11 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): EEG signal by setting ``ref_channels='average'``. Bad EEG channels are automatically excluded if they are properly set in ``info['bads']``. + .. note:: + If you wish to add a new reference channel (e.g., a mastoid) + to the data, use :func:`mne.add_reference_channels` + **before** calling this function. + - A single electrode: Set ``ref_channels`` to a list containing the name of the channel that will act as the new reference, for example ``ref_channels=['Cz']``. diff --git a/tutorials/preprocessing/55_setting_eeg_reference.py b/tutorials/preprocessing/55_setting_eeg_reference.py index 770af624de7..813b38e603e 100644 --- a/tutorials/preprocessing/55_setting_eeg_reference.py +++ b/tutorials/preprocessing/55_setting_eeg_reference.py @@ -146,6 +146,11 @@ # # Creating the average reference as a projector # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +# .. note:: +# If you wish to add a new reference channel (e.g., a mastoid) +# to the data, use :func:`mne.add_reference_channels` +# **before** calling this function. # # If using an average reference, it is possible to create the reference as a # :term:`projector` rather than subtracting the reference from the data From c3ecfd20bba22d93fe9462235e8e751509b00fb3 Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Thu, 23 Apr 2026 15:50:16 +0530 Subject: [PATCH 05/17] DOC: address review - add sensor-space detail and citation --- doc/references.bib | 10 ++++++++++ mne/utils/docs.py | 11 ++++++----- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/doc/references.bib b/doc/references.bib index c7eefd9e808..02608d797a1 100644 --- a/doc/references.bib +++ b/doc/references.bib @@ -2566,3 +2566,13 @@ @inproceedings{MellotEtAl2024 year = {2024}, address = {Lyon, France} } + +@article{AppelhoffSanderson2023, + author = {Appelhoff, Stefan and Sanderson, Nathan}, + title = {The importance of adding a zero-filled channel for the reference electrode when re-referencing to average reference}, + journal = {Frontiers in Signal Processing}, + year = {2023}, + doi = {10.3389/frsip.2023.1064138}, + volume = {3}, + pages = {1064138} +} \ No newline at end of file diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 0800e7bf33f..70b3fe03970 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4104,12 +4104,13 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): - Average reference: A new virtual reference electrode is created by averaging the current EEG signal by setting ``ref_channels='average'``. Bad EEG channels are - automatically excluded if they are properly set in ``info['bads']``. + automatically excluded if they are pproperly set in ``info['bads']``. - .. note:: - If you wish to add a new reference channel (e.g., a mastoid) - to the data, use :func:`mne.add_reference_channels` - **before** calling this function. + "add_reference_channels_note": """.. note:: When performing average referencing in sensor-space analyses and the + original reference electrode is not present as a zero-filled channel, + this must first be added using :func:`~mne.add_reference_channels` + before calling :func:`~mne.set_eeg_reference` to avoid biasing the + reference :footcite:`AppelhoffSanderson2023`. """, - A single electrode: Set ``ref_channels`` to a list containing the name of the channel that From dbee994f699d0eaa49b71cfa5034fd990aa4a8ed Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Thu, 23 Apr 2026 18:01:28 +0530 Subject: [PATCH 06/17] DOC: expand tutorial note to match sensor-space detail --- tutorials/preprocessing/55_setting_eeg_reference.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/tutorials/preprocessing/55_setting_eeg_reference.py b/tutorials/preprocessing/55_setting_eeg_reference.py index 813b38e603e..ace7fd99bbe 100644 --- a/tutorials/preprocessing/55_setting_eeg_reference.py +++ b/tutorials/preprocessing/55_setting_eeg_reference.py @@ -147,10 +147,12 @@ # Creating the average reference as a projector # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -# .. note:: -# If you wish to add a new reference channel (e.g., a mastoid) -# to the data, use :func:`mne.add_reference_channels` -# **before** calling this function. +# .. note:: When performing average referencing in sensor-space analyses and +# the original reference electrode is not present as a zero-filled +# channel, this must first be added using +# :func:`~mne.add_reference_channels` before calling +# :func:`~mne.set_eeg_reference` to avoid biasing the reference +# :footcite:`AppelhoffSanderson2023`. # # If using an average reference, it is possible to create the reference as a # :term:`projector` rather than subtracting the reference from the data From f26d3056dc5225564f957db70fd73cc372d0f791 Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Thu, 23 Apr 2026 18:11:27 +0530 Subject: [PATCH 07/17] DOC: remove irrelevant note from add_reference_channels --- mne/channels/channels.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/mne/channels/channels.py b/mne/channels/channels.py index c8ee5f74d57..e90b75d62c5 100644 --- a/mne/channels/channels.py +++ b/mne/channels/channels.py @@ -813,11 +813,7 @@ def add_reference_channels(self, ref_channels): inst : same type as the input data The modified instance. - note:: If you are adding a new reference channel to data that - will eventually be used with an average reference, - you should also call :meth:`mne.io.Raw.set_eeg_reference` - (or the equivalent Epochs/Evoked method) to ensure the - mathematical reference is updated correctly. + """ return add_reference_channels(self, ref_channels, copy=False) From effcec12f4b38d6f4f8a81749eddf5a6e622a04d Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 23 Apr 2026 12:42:07 +0000 Subject: [PATCH 08/17] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- mne/channels/channels.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mne/channels/channels.py b/mne/channels/channels.py index e90b75d62c5..0e4f26fd6f9 100644 --- a/mne/channels/channels.py +++ b/mne/channels/channels.py @@ -813,7 +813,7 @@ def add_reference_channels(self, ref_channels): inst : same type as the input data The modified instance. - + """ return add_reference_channels(self, ref_channels, copy=False) From a2eb16cee8cda98598b40aa9fa08637efbd84eb9 Mon Sep 17 00:00:00 2001 From: Deep Date: Fri, 1 May 2026 10:02:59 +0530 Subject: [PATCH 09/17] Update mne/utils/docs.py fix: correct typo in docs.py Co-authored-by: Thomas S. Binns --- mne/utils/docs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 03b87b7b08b..e1587b83c8a 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4104,7 +4104,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): - Average reference: A new virtual reference electrode is created by averaging the current EEG signal by setting ``ref_channels='average'``. Bad EEG channels are - automatically excluded if they are pproperly set in ``info['bads']``. + automatically excluded if they are properly set in ``info['bads']``. "add_reference_channels_note": """.. note:: When performing average referencing in sensor-space analyses and the original reference electrode is not present as a zero-filled channel, From d6839bb0280fee28cb185dfea115285f73ab2531 Mon Sep 17 00:00:00 2001 From: Deep Date: Fri, 1 May 2026 10:08:17 +0530 Subject: [PATCH 10/17] Update mne/utils/docs.py doc: reformat reference channel note for clarity Co-authored-by: Thomas S. Binns --- mne/utils/docs.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/mne/utils/docs.py b/mne/utils/docs.py index e1587b83c8a..117b0ff67b1 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4106,11 +4106,12 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): EEG signal by setting ``ref_channels='average'``. Bad EEG channels are automatically excluded if they are properly set in ``info['bads']``. - "add_reference_channels_note": """.. note:: When performing average referencing in sensor-space analyses and the - original reference electrode is not present as a zero-filled channel, - this must first be added using :func:`~mne.add_reference_channels` - before calling :func:`~mne.set_eeg_reference` to avoid biasing the - reference :footcite:`AppelhoffSanderson2023`. """, +.. note:: + When performing average referencing in sensor-space analyses and the original + reference electrode is not present as a zero-filled channel, this must first be + added using :func:`~mne.add_reference_channels`, before calling + :func:`~mne.set_eeg_reference`. This is necessary to avoid biasing the reference + :footcite:`AppelhoffSanderson2023`. - A single electrode: Set ``ref_channels`` to a list containing the name of the channel that From cbb05961e723e95529c167e3021b5ca6faf4ebca Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Fri, 1 May 2026 10:28:26 +0530 Subject: [PATCH 11/17] DOC: remove blank lines --- mne/channels/channels.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/mne/channels/channels.py b/mne/channels/channels.py index 0e4f26fd6f9..c1a3d462525 100644 --- a/mne/channels/channels.py +++ b/mne/channels/channels.py @@ -812,8 +812,6 @@ def add_reference_channels(self, ref_channels): ------- inst : same type as the input data The modified instance. - - """ return add_reference_channels(self, ref_channels, copy=False) From 0d98056cdd1d845aa8bc1731665c316d6a3dd4be Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Fri, 1 May 2026 10:38:21 +0530 Subject: [PATCH 12/17] DOC: fix citation details and alphabetize bibliography --- doc/references.bib | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/references.bib b/doc/references.bib index 02608d797a1..6a905098a8f 100644 --- a/doc/references.bib +++ b/doc/references.bib @@ -4,6 +4,16 @@ # not both, as the DOI turns into a link which is redundant with the URL. % MNE-C reference +@article{AppelhoffSanderson2023, + author = {Appelhoff, Stefan and Sanderson, Nathan J.}, + title = {The importance of adding a zero-filled channel for the reference electrode when re-referencing {EEG} data}, + journal = {Frontiers in Signal Processing}, + year = {2023}, + doi = {10.3389/frsip.2023.1064138}, + volume = {3}, + pages = {1064138} + doi = {10.3389/frsip.2023.1064138}, +} @article{GramfortEtAl2014, title = {{{MNE}} Software for Processing {{MEG}} and {{EEG}} Data}, author = {Gramfort, Alexandre and Luessi, Martin and Larson, Eric and Engemann, Denis A. and Strohmeier, Daniel and Brodbeck, Christian and Parkkonen, Lauri and H{\"a}m{\"a}l{\"a}inen, Matti S.}, @@ -2566,13 +2576,3 @@ @inproceedings{MellotEtAl2024 year = {2024}, address = {Lyon, France} } - -@article{AppelhoffSanderson2023, - author = {Appelhoff, Stefan and Sanderson, Nathan}, - title = {The importance of adding a zero-filled channel for the reference electrode when re-referencing to average reference}, - journal = {Frontiers in Signal Processing}, - year = {2023}, - doi = {10.3389/frsip.2023.1064138}, - volume = {3}, - pages = {1064138} -} \ No newline at end of file From 87cd94fcf8ab21453a2738c8c0990f816eaa5bd8 Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Fri, 1 May 2026 10:48:20 +0530 Subject: [PATCH 13/17] MAINT: update changelog name and text --- doc/changes/dev/13618.notable.rst | 1 - doc/changes/dev/13846.other.rst | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) delete mode 100644 doc/changes/dev/13618.notable.rst create mode 100644 doc/changes/dev/13846.other.rst diff --git a/doc/changes/dev/13618.notable.rst b/doc/changes/dev/13618.notable.rst deleted file mode 100644 index 10202f8c55a..00000000000 --- a/doc/changes/dev/13618.notable.rst +++ /dev/null @@ -1 +0,0 @@ -Clarify average EEG reference behavior in documentation for add_reference_channels. \ No newline at end of file diff --git a/doc/changes/dev/13846.other.rst b/doc/changes/dev/13846.other.rst new file mode 100644 index 00000000000..1a0a8548571 --- /dev/null +++ b/doc/changes/dev/13846.other.rst @@ -0,0 +1 @@ +Clarify average EEG reference behavior in documentation for :func:`~mne.add_reference_channels`, by `Deep Kaur`_ (:newcontrib:`Deep Kaur`) \ No newline at end of file From 2b24fca9c5c6415bb8c0b36e5078b4885a36ea9d Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Sun, 3 May 2026 19:03:15 +0530 Subject: [PATCH 14/17] DOC: fix bibliography location, authors, and duplicate DOI --- doc/references.bib | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/doc/references.bib b/doc/references.bib index 6a905098a8f..ac1b2e39783 100644 --- a/doc/references.bib +++ b/doc/references.bib @@ -4,16 +4,6 @@ # not both, as the DOI turns into a link which is redundant with the URL. % MNE-C reference -@article{AppelhoffSanderson2023, - author = {Appelhoff, Stefan and Sanderson, Nathan J.}, - title = {The importance of adding a zero-filled channel for the reference electrode when re-referencing {EEG} data}, - journal = {Frontiers in Signal Processing}, - year = {2023}, - doi = {10.3389/frsip.2023.1064138}, - volume = {3}, - pages = {1064138} - doi = {10.3389/frsip.2023.1064138}, -} @article{GramfortEtAl2014, title = {{{MNE}} Software for Processing {{MEG}} and {{EEG}} Data}, author = {Gramfort, Alexandre and Luessi, Martin and Larson, Eric and Engemann, Denis A. and Strohmeier, Daniel and Brodbeck, Christian and Parkkonen, Lauri and H{\"a}m{\"a}l{\"a}inen, Matti S.}, @@ -35,6 +25,15 @@ @article{GramfortEtAl2013a number = {267} } % everything else +@article{AppelhoffSanderson2023, + author = {Appelhoff, Stefan and Sanderson, Nathan J.}, + title = {The importance of adding a zero-filled channel for the reference electrode when re-referencing {EEG} data}, + journal = {Frontiers in Signal Processing}, + year = {2023}, + volume = {3}, + pages = {1064138}, + doi = {10.3389/frsip.2023.1064138}, +} @article{NolanEtAl2010, author = {Nolan, H. and Whelan, R. and Reilly, R. B.}, title = {{FASTER}: Fully Automated Statistical Thresholding for {EEG} artifact Rejection}, From 2f339786768d42ded164ed094ab979fff71886f7 Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Sun, 3 May 2026 19:09:03 +0530 Subject: [PATCH 15/17] DOC: fix indentation in tutorial note --- tutorials/preprocessing/55_setting_eeg_reference.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tutorials/preprocessing/55_setting_eeg_reference.py b/tutorials/preprocessing/55_setting_eeg_reference.py index ace7fd99bbe..6a7bef71902 100644 --- a/tutorials/preprocessing/55_setting_eeg_reference.py +++ b/tutorials/preprocessing/55_setting_eeg_reference.py @@ -147,12 +147,12 @@ # Creating the average reference as a projector # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -# .. note:: When performing average referencing in sensor-space analyses and -# the original reference electrode is not present as a zero-filled -# channel, this must first be added using -# :func:`~mne.add_reference_channels` before calling -# :func:`~mne.set_eeg_reference` to avoid biasing the reference -# :footcite:`AppelhoffSanderson2023`. +# .. note:: +# When performing average referencing in sensor-space analyses and the original +# reference electrode is not present as a zero-filled channel, this must first be +# added using :func:`~mne.add_reference_channels` before calling +# :func:`~mne.set_eeg_reference`. This is necessary to avoid biasing the reference +# :footcite:`AppelhoffSanderson2023`. # # If using an average reference, it is possible to create the reference as a # :term:`projector` rather than subtracting the reference from the data From 6e49874b0d1d8c78d6d910c76b78036631f3cca1 Mon Sep 17 00:00:00 2001 From: Deep Date: Sun, 3 May 2026 19:14:00 +0530 Subject: [PATCH 16/17] Update doc/changes/dev/13846.other.rst Add notes to :func:`~mne.set_eeg_reference` and :ref:`_tut-set-eeg-ref` about the correct procedure to create an average reference, by :newcontrib:`Deep Kaur`. Co-authored-by: Thomas S. Binns --- doc/changes/dev/13846.other.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/changes/dev/13846.other.rst b/doc/changes/dev/13846.other.rst index 1a0a8548571..ac0f5f9295f 100644 --- a/doc/changes/dev/13846.other.rst +++ b/doc/changes/dev/13846.other.rst @@ -1 +1 @@ -Clarify average EEG reference behavior in documentation for :func:`~mne.add_reference_channels`, by `Deep Kaur`_ (:newcontrib:`Deep Kaur`) \ No newline at end of file +Add notes to :func:`~mne.set_eeg_reference` and :ref:`_tut-set-eeg-ref` about the correct procedure to create an average reference, by :newcontrib:`Deep Kaur`. \ No newline at end of file From ec318e6a3a232061d37c2b02e31ee05f7df0ff27 Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Sun, 3 May 2026 19:27:02 +0530 Subject: [PATCH 17/17] MAINT: add Deep Kaur to names.inc --- doc/changes/names.inc | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/changes/names.inc b/doc/changes/names.inc index d7349b1eac9..38ff8b7dc17 100644 --- a/doc/changes/names.inc +++ b/doc/changes/names.inc @@ -70,6 +70,7 @@ .. _David Haslacher: https://github.com/davidhaslacher .. _David Julien: https://github.com/Swy7ch .. _David Sabbagh: https://github.com/DavidSabbagh +.. _Deep Kaur: https://github.com/Dpereaptkhamur-13 .. _Demetres Kostas: https://github.com/kostasde .. _Denis Engemann: https://denis-engemann.de .. _Dev Parikh: https://github.com/devparikh0506