diff --git a/doc/changes/dev/13618.notable.rst b/doc/changes/dev/13618.notable.rst new file mode 100644 index 00000000000..10202f8c55a --- /dev/null +++ b/doc/changes/dev/13618.notable.rst @@ -0,0 +1 @@ +Clarify average EEG reference behavior in documentation for add_reference_channels. \ No newline at end of file diff --git a/mne/channels/channels.py b/mne/channels/channels.py index c1a3d462525..c8ee5f74d57 100644 --- a/mne/channels/channels.py +++ b/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) diff --git a/mne/utils/docs.py b/mne/utils/docs.py index e079e2dd63c..0800e7bf33f 100644 --- a/mne/utils/docs.py +++ b/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']``. diff --git a/tutorials/preprocessing/55_setting_eeg_reference.py b/tutorials/preprocessing/55_setting_eeg_reference.py index 770af624de7..813b38e603e 100644 --- a/tutorials/preprocessing/55_setting_eeg_reference.py +++ b/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