DOC: clarify add_reference_channels usage (Takeover #13664)

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`.

doc/changes/names.inc

@@ -71,6 +71,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

doc/references.bib

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

mne/utils/docs.py

@@ -4106,6 +4106,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 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
     will act as the new reference, for example ``ref_channels=['Cz']``.

tutorials/preprocessing/55_setting_eeg_reference.py

@@ -146,6 +146,13 @@
 #
 # 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