From 76687f2bc0ba9457d5ba4d0bf4a4320f4c75caf3 Mon Sep 17 00:00:00 2001 From: Farzah11 Date: Tue, 17 Feb 2026 13:12:24 +0500 Subject: [PATCH 1/4] DOC: clarify average EEG reference behavior and update tutorial note --- mne/_fiff/reference.py | 12 ++++++++++++ tutorials/preprocessing/55_setting_eeg_reference.py | 7 +++++++ 2 files changed, 19 insertions(+) diff --git a/mne/_fiff/reference.py b/mne/_fiff/reference.py index 13fed0eebd2..7d0133a4632 100644 --- a/mne/_fiff/reference.py +++ b/mne/_fiff/reference.py @@ -404,6 +404,18 @@ def set_eeg_reference( Array of reference data subtracted from EEG channels. This will be ``None`` if ``projection=True``, or if ``ref_channels`` is ``"REST"`` or a :class:`dict`. + + Notes + ----- + When using ``ref_channels="average"`` with ``projection=False`` (the + default), the average reference is computed over the EEG channels present + in the data. If the original reference electrode was not recorded as a + channel (or was removed during acquisition or preprocessing), it is not + implicitly accounted for in the average. + For sensor-space analyses where this distinction matters, consider adding + a zero-filled reference channel using :func:`add_reference_channel` before + applying the average reference. + %(set_eeg_reference_see_also_notes)s """ from ..forward import Forward diff --git a/tutorials/preprocessing/55_setting_eeg_reference.py b/tutorials/preprocessing/55_setting_eeg_reference.py index 770af624de7..36698fe49c2 100644 --- a/tutorials/preprocessing/55_setting_eeg_reference.py +++ b/tutorials/preprocessing/55_setting_eeg_reference.py @@ -141,6 +141,13 @@ raw_avg_ref = raw.copy().set_eeg_reference(ref_channels="average") raw_avg_ref.plot() +# Note: +# When computing an average reference, if the dataset does not include the original +# reference electrode, the average will be biased because the missing channel is ignored. +# To avoid this, first add a zero-valued reference channel using +# mne.add_reference_channels(). This ensures that all intended channels, +# including the original reference, contribute correctly to the average. + # %% # .. _section-avg-ref-proj: # From f44ea8f6f5b8e43b4533b3291c10e25bb1e5a048 Mon Sep 17 00:00:00 2001 From: Farzah11 Date: Mon, 23 Feb 2026 01:29:00 +0500 Subject: [PATCH 2/4] DOC: Fix average reference documentation structure - Move average reference note to docs.py (set_eeg_reference_see_also_notes) - Remove floating text from reference.py docstring - Add note to tutorial about using add_reference_channels for correct avg ref - Include Kim et al. (2023) paper reference - Fix line lengths to comply with PEP 8 (<= 79 chars) --- mne/_fiff/reference.py | 11 ----------- mne/utils/docs.py | 9 +++++++++ tutorials/preprocessing/55_setting_eeg_reference.py | 13 +++++++------ 3 files changed, 16 insertions(+), 17 deletions(-) diff --git a/mne/_fiff/reference.py b/mne/_fiff/reference.py index 7d0133a4632..f3757c32d0f 100644 --- a/mne/_fiff/reference.py +++ b/mne/_fiff/reference.py @@ -405,17 +405,6 @@ def set_eeg_reference( ``None`` if ``projection=True``, or if ``ref_channels`` is ``"REST"`` or a :class:`dict`. - Notes - ----- - When using ``ref_channels="average"`` with ``projection=False`` (the - default), the average reference is computed over the EEG channels present - in the data. If the original reference electrode was not recorded as a - channel (or was removed during acquisition or preprocessing), it is not - implicitly accounted for in the average. - For sensor-space analyses where this distinction matters, consider adding - a zero-filled reference channel using :func:`add_reference_channel` before - applying the average reference. - %(set_eeg_reference_see_also_notes)s """ from ..forward import Forward diff --git a/mne/utils/docs.py b/mne/utils/docs.py index fc7d33a6f4b..53f2f0a1784 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4103,6 +4103,15 @@ 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']``. + For sensor-space analyses, if the original reference electrode is not + present as a channel, the resulting average reference is biased because + the subtracted signal is divided by n channels instead of n + 1 + (including the reference). For a correct average reference, add a + zero-filled reference channel with :func:`~mne.add_reference_channels` + before calling :func:`~mne.set_eeg_reference`. For further discussion, + see Kim et al. (2023) `Frontiers in Signal Processing + `__. + - 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 36698fe49c2..50e762545f5 100644 --- a/tutorials/preprocessing/55_setting_eeg_reference.py +++ b/tutorials/preprocessing/55_setting_eeg_reference.py @@ -141,12 +141,13 @@ raw_avg_ref = raw.copy().set_eeg_reference(ref_channels="average") raw_avg_ref.plot() -# Note: -# When computing an average reference, if the dataset does not include the original -# reference electrode, the average will be biased because the missing channel is ignored. -# To avoid this, first add a zero-valued reference channel using -# mne.add_reference_channels(). This ensures that all intended channels, -# including the original reference, contribute correctly to the average. +# .. note:: +# When computing an average reference, if the dataset does not include +# the original reference electrode, the average will be biased because the +# missing channel is ignored. To avoid this, first add a zero-valued +# reference channel using :func:`mne.add_reference_channels`. This ensures +# that all intended channels, including the original reference, contribute +# correctly to the average. # %% # .. _section-avg-ref-proj: From 868960b9342c64e5297dbaa220fd28565088f0da Mon Sep 17 00:00:00 2001 From: Farzah11 Date: Mon, 23 Feb 2026 01:53:47 +0500 Subject: [PATCH 3/4] DOC: Use footcite for paper reference and add to references.bib --- doc/references.bib | 10 ++++++++++ mne/utils/docs.py | 3 +-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/doc/references.bib b/doc/references.bib index 12d63458bd1..981d45fcd21 100644 --- a/doc/references.bib +++ b/doc/references.bib @@ -1028,6 +1028,16 @@ @article{KriegeskorteEtAl2008 year = {2008} } +@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 ICs emerge from effective rank deficiency caused by EEG electrode interpolation and incorrect re-referencing}}, + volume = {3}, + year = {2023} +} + @article{LaaksoCottrell2000, author = {Laakso, Aarre and Cottrell, Garrison}, doi = {10.1080/09515080050002726}, diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 53f2f0a1784..e91c25b55b8 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4109,8 +4109,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): (including the reference). For a correct average reference, add a zero-filled reference channel with :func:`~mne.add_reference_channels` before calling :func:`~mne.set_eeg_reference`. For further discussion, - see Kim et al. (2023) `Frontiers in Signal Processing - `__. + see :footcite:t:`KimEtAl2023`. - A single electrode: Set ``ref_channels`` to a list containing the name of the channel that From fe3841c4614e1ca65de723e05c59c08bed2a2d2d Mon Sep 17 00:00:00 2001 From: Farzah11 Date: Mon, 23 Feb 2026 02:07:22 +0500 Subject: [PATCH 4/4] DOC: Use plain text citation instead of footcite --- doc/references.bib | 10 ---------- mne/utils/docs.py | 2 +- 2 files changed, 1 insertion(+), 11 deletions(-) diff --git a/doc/references.bib b/doc/references.bib index 981d45fcd21..12d63458bd1 100644 --- a/doc/references.bib +++ b/doc/references.bib @@ -1028,16 +1028,6 @@ @article{KriegeskorteEtAl2008 year = {2008} } -@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 ICs emerge from effective rank deficiency caused by EEG electrode interpolation and incorrect re-referencing}}, - volume = {3}, - year = {2023} -} - @article{LaaksoCottrell2000, author = {Laakso, Aarre and Cottrell, Garrison}, doi = {10.1080/09515080050002726}, diff --git a/mne/utils/docs.py b/mne/utils/docs.py index e91c25b55b8..9133bb92eb6 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4109,7 +4109,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): (including the reference). For a correct average reference, add a zero-filled reference channel with :func:`~mne.add_reference_channels` before calling :func:`~mne.set_eeg_reference`. For further discussion, - see :footcite:t:`KimEtAl2023`. + see Kim et al. (2023, doi:10.3389/frsip.2023.1064138). - A single electrode: Set ``ref_channels`` to a list containing the name of the channel that