DOC: clarify add_reference_channels usage (Takeover #13664)

doc/changes/dev/13618.notable.rst

@@ -0,0 +1 @@
+Clarify average EEG reference behavior in documentation for add_reference_channels.

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}
+}

mne/channels/channels.py

@@ -812,6 +812,8 @@ 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)
 

mne/utils/docs.py

@@ -4104,7 +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']``.
+
+    "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

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