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.

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)
 

mne/utils/docs.py

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

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