From b8cb797547a453d09949ec0beed10fb80646e89d Mon Sep 17 00:00:00 2001 From: Deep Kaur Date: Wed, 8 Apr 2026 15:49:44 +0530 Subject: [PATCH 01/21] 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/21] 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/21] [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/21] 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/21] 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/21] 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/21] 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/21] [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/21] 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/21] 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/21] 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/21] 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/21] 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/21] 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/21] 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/21] 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/21] 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 From b2952b4be66ff2e5a085944dfc76fc915433c725 Mon Sep 17 00:00:00 2001 From: "Thomas S. Binns" Date: Thu, 7 May 2026 18:22:51 +0100 Subject: [PATCH 18/21] Add original PR author to changelog --- doc/changes/dev/13846.other.rst | 2 +- doc/changes/names.inc | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/changes/dev/13846.other.rst b/doc/changes/dev/13846.other.rst index ac0f5f9295f..1528fbdb899 100644 --- a/doc/changes/dev/13846.other.rst +++ b/doc/changes/dev/13846.other.rst @@ -1 +1 @@ -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 +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` and :newcontrib:`Farzah11`. \ No newline at end of file diff --git a/doc/changes/names.inc b/doc/changes/names.inc index 747ad10fe4b..e8a2b3a139e 100644 --- a/doc/changes/names.inc +++ b/doc/changes/names.inc @@ -101,6 +101,7 @@ .. _Ezequiel Mikulan: https://github.com/ezemikulan .. _Fahimeh Mamashli: https://github.com/fmamashli .. _Famous077: https://github.com/Famous077 +.. _Farzah11: https://github.com/Farzah11 .. _Farzin Negahbani: https://github.com/Farzin-Negahbani .. _Federico Raimondo: https://github.com/fraimondo .. _Federico Zamberlan: https://github.com/fzamberlan From 2428efb0ff2c6e47c4b182c9a2ec303d13e5a756 Mon Sep 17 00:00:00 2001 From: "Thomas S. Binns" Date: Thu, 7 May 2026 19:01:15 +0100 Subject: [PATCH 19/21] Update wording --- mne/utils/docs.py | 8 ++++---- .../preprocessing/55_setting_eeg_reference.py | 18 +++++++++++------- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 117b0ff67b1..2456f9db287 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4107,11 +4107,11 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): automatically excluded if they are properly set in ``info['bads']``. .. 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 + When performing average referencing in sensor-space analyses, the original reference + electrode should be present as a zero-filled channel. If it is not, 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`. + :footcite:`KimEtAl2023`. - A single electrode: Set ``ref_channels`` to a list containing the name of the channel that diff --git a/tutorials/preprocessing/55_setting_eeg_reference.py b/tutorials/preprocessing/55_setting_eeg_reference.py index 6a7bef71902..9b4d339d16a 100644 --- a/tutorials/preprocessing/55_setting_eeg_reference.py +++ b/tutorials/preprocessing/55_setting_eeg_reference.py @@ -141,18 +141,22 @@ raw_avg_ref = raw.copy().set_eeg_reference(ref_channels="average") raw_avg_ref.plot() +# %% +# .. note:: +# When performing average referencing in sensor-space analyses, the original reference +# electrode should be present as a zero-filled channel. If it is not, 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:`KimEtAl2023`, as the subtracted reference signal would be divided by +# `n_channels` instead of the correct `n_channels + 1` (i.e., including the original +# reference channel). +# + # %% # .. _section-avg-ref-proj: # # 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`. 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 5d8f1450f4e1cdda409fef0cfac45a95230b2f05 Mon Sep 17 00:00:00 2001 From: "Thomas S. Binns" Date: Thu, 7 May 2026 19:01:54 +0100 Subject: [PATCH 20/21] Fix incorrect reference info --- doc/references.bib | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/doc/references.bib b/doc/references.bib index ac1b2e39783..04b822ddabc 100644 --- a/doc/references.bib +++ b/doc/references.bib @@ -25,15 +25,6 @@ @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}, @@ -981,6 +972,16 @@ @article{KhanEtAl2018 year = {2018} } +@article{KimEtAl2023, + author = {Kim, Hyeonseok and Luo, Justin and Chu, Shannon and Cannard, Cedric and Hoffmann, Sven and Miyakoshi, Makoto}, + doi = {10.3389/frsip.2023.1064138}, + journal={Frontiers in Signal Processing}, + pages = {1064138}, + title={{ICA}’s bug: How ghost {IC}s emerge from effective rank deficiency caused by {EEG} electrode interpolation and incorrect re-referencing}, + volume = {3}, + year = {2023}, +} + @article{KingDehaene2014, author = {King, Jean-Rémi and Dehaene, Stanislas}, doi = {10.1016/j.tics.2014.01.002}, From 1461cef678a8b13825e1101fc65883832dfab152 Mon Sep 17 00:00:00 2001 From: "Thomas S. Binns" Date: Sun, 10 May 2026 18:52:13 +0100 Subject: [PATCH 21/21] Add original PR author [skip actions][skip azp] Co-authored-by: Farzah11 <184847039+Farzah11@users.noreply.github.com>