DOC: clarify add_reference_channels usage (Takeover #13664) (#13846)

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: Farzah11 <184847039+Farzah11@users.noreply.github.com>

Author: 4 people

doc/changes/dev/13846.other.rst

@@ -0,0 +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` and :newcontrib:`Farzah11`.

doc/changes/names.inc

@@ -74,6 +74,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
@@ -103,6 +104,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

doc/references.bib

@@ -972,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},

mne/utils/docs.py

@@ -4173,6 +4173,13 @@ 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::
+    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`.
+
 - 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']``.

tutorials/preprocessing/55_setting_eeg_reference.py

@@ -141,6 +141,16 @@
 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:
 #