DOC: clarify add_reference_channels usage (Takeover #13664) by Dpereaptkhamur-13 · Pull Request #13846 · mne-tools/mne-python

Dpereaptkhamur-13 · 2026-04-16T14:15:14Z

Reference issue (if any)

What does this implement/fix?

This PR completes the documentation clarification for add_reference_channels originally started in #13664. It addresses the mathematical requirements for average referencing in the docstrings, as requested in issue #13618.
Changes include:

Added an explicit note to the add_reference_channels docstring explaining average reference recomputation.
Included a properly formatted towncrier entry in doc/changes/dev/13618.notable.rst to resolve the check failures seen in the previous PR.

Additional information

for more information, see https://pre-commit.ci

HansujaB · 2026-04-18T18:34:41Z

Hey @Dpereaptkhamur-13 , I believe you don't have an account on circle ci that's why those checks are failing , login into your account & those tests will pass !

Dpereaptkhamur-13 · 2026-04-19T01:43:32Z

Hi @HansujaB, thank you for the tip! I have now logged into CircleCI and authorized the account. The tests should be ready to run once a maintainer approves the workflow. Thanks again for the help!

tsbinns · 2026-04-20T16:46:53Z

Hi @Dpereaptkhamur-13, thanks for opening the PR.

Right now, the message has been added to add_reference_channels. However, the risk is that people are calling set_eeg_reference without calling add_reference_channels first. So, this note about the proper procedure could be easily missed by the people who need to see it most.

Rather, the note should be included in set_eeg_reference, such that people see this, and then go back to use add_refence_channels. I'd suggest looking at how this was handled in #13664 and adding the note to the docdict: https://github.com/Farzah11/mne-python/blob/a8e92a3a7d8a83a021d81da9c6b1b38f678ad53f/mne/utils/docs.py#L4106-L4112

Just make sure if you use this text to action the suggested changes: https://github.com/mne-tools/mne-python/pull/13664/changes#r2892847499 and https://github.com/mne-tools/mne-python/pull/13664/changes#r2892851172

Then, it would be good to also add a note to the setting_eeg_reference tutorial, similar to in #13664: https://github.com/Farzah11/mne-python/blob/a8e92a3a7d8a83a021d81da9c6b1b38f678ad53f/tutorials/preprocessing/55_setting_eeg_reference.py#L144-L150
However, also keep in mind the formatting suggestion to get this to render properly: https://github.com/mne-tools/mne-python/pull/13664/changes#r2892854083

Dpereaptkhamur-13 · 2026-04-21T02:44:31Z

Hi @tsbinns, thank you for the detailed feedback! That makes complete sense—moving the clarification to set_eeg_reference and the tutorials ensures it's visible to users regardless of which function they check first. I will update mne/utils/docs.py and the preprocessing tutorial file accordingly. I'll ping you again once the changes are pushed!

…ereaptkhamur-15/mne-python into doc-ref-channel-clarification

tsbinns · 2026-04-22T19:50:27Z

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


I'd suggest specifically mentioning average referencing for sensor-space analyses. E.g.:

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.

Also, please add a citation for the paper where this gets discussed (10.3389/frsip.2023.1064138). Have a look at :footcite: and :footbibliography: for examples of doing this after adding the citation to our BibTeX file.

Hi @drammock, I've updated the documentation note with the sensor-space details and added the citation to references.bib as requested. I also included the footbibliography in the tutorial. Ready for another look!

tsbinns · 2026-04-22T19:51:23Z

+
+# .. 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.


Please make this comment a bit more detailed, like in the previous PR: https://github.com/Farzah11/mne-python/blob/a8e92a3a7d8a83a021d81da9c6b1b38f678ad53f/tutorials/preprocessing/55_setting_eeg_reference.py#L144-L150

I have updated the tutorial note on line 150 with the expanded detail and citation as suggested. All feedback from the review should now be addressed. Thanks for the guidance!

tsbinns · 2026-04-22T19:53:14Z

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


This information isn't so relevant to add_reference_channels. The purpose of this function isn't to change the reference, it just adds zero-filled channels.

I have addressed all the feedback:

Removed the irrelevant note from mne/channels/channels.py.

Expanded the note in the tutorial with sensor-space details and the citation.

Added the bibliography to the tutorial file.

Everything should be consistent now. Thank you for the detailed reviews!

…ereaptkhamur-13/mne-python into doc-ref-channel-clarification

for more information, see https://pre-commit.ci

tsbinns · 2026-04-23T16:57:33Z

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


Suggested change

automatically excluded if they are pproperly set in ``info['bads']``.

automatically excluded if they are properly set in ``info['bads']``.

tsbinns · 2026-04-23T17:03:22Z

+    "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`. """,


Suggested change

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

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

tsbinns · 2026-04-23T17:04:16Z

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


Please copy the changes from the note in the docstring, including the proper formatting.

tsbinns · 2026-04-23T17:05:17Z

+
+

Please remove these blank lines.

tsbinns · 2026-04-23T17:12:26Z

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


Two things:

This author and title information is wrong. This needs to be corrected.

The bibliography file isn't perfectly alphabetical, but please try to stick the citation in roughly the right place, not just at the end of the file.

tsbinns · 2026-04-23T17:17:32Z

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


A couple things:

Now that the changes for this PR are a bit clearer, the changelog entry text should be updated.

You would need to add your name with the newcontrib tag to the end of the text.

The number in the file name must match the PR number.

This is not a notable change. other would be more appropriate.

Precise details for all of this are in the contribution guide. Please follow the instructions there.

Dpereaptkhamur-13 added 2 commits April 8, 2026 15:49

DOC: Clarify add_reference_channels usage with average reference

b8cb797

DOC: take over mne-tools#13664 to clarify avg behavior and add towncrier

e270d35

Dpereaptkhamur-13 requested review from agramfort, drammock, larsoner and mscheltienne as code owners April 16, 2026 14:15

pre-commit-ci Bot and others added 2 commits April 16, 2026 14:15

[pre-commit.ci] auto fixes from pre-commit.com hooks

5ecd0c0

for more information, see https://pre-commit.ci

Merge branch 'main' into doc-ref-channel-clarification

f261a66

Merge branch 'main' into doc-ref-channel-clarification

2231721

Dpereaptkhamur-13 added 3 commits April 22, 2026 10:10

DOC: move and reformat avg ref note

e110c7c

Merge branch 'doc-ref-channel-clarification' of https://github.com/Dp…

922c26f

…ereaptkhamur-15/mne-python into doc-ref-channel-clarification

Merge branch 'main' into doc-ref-channel-clarification

d39b245

tsbinns requested changes Apr 22, 2026

View reviewed changes

Dpereaptkhamur-13 and others added 5 commits April 23, 2026 15:50

DOC: address review - add sensor-space detail and citation

c3ecfd2

Merge branch 'doc-ref-channel-clarification' of https://github.com/Dp…

2bef1d5

…ereaptkhamur-13/mne-python into doc-ref-channel-clarification

DOC: expand tutorial note to match sensor-space detail

dbee994

DOC: remove irrelevant note from add_reference_channels

f26d305

[pre-commit.ci] auto fixes from pre-commit.com hooks

effcec1

for more information, see https://pre-commit.ci

tsbinns requested changes Apr 23, 2026

View reviewed changes

	automatically excluded if they are pproperly set in ``info['bads']``.
	automatically excluded if they are properly set in ``info['bads']``.

		@@ -0,0 +1 @@
		Clarify average EEG reference behavior in documentation for add_reference_channels. No newline at end of file

Uh oh!

Conversation

Dpereaptkhamur-13 commented Apr 16, 2026

Reference issue (if any)

What does this implement/fix?

Additional information

Uh oh!

HansujaB commented Apr 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Dpereaptkhamur-13 commented Apr 19, 2026

Uh oh!

tsbinns commented Apr 20, 2026

Uh oh!

Dpereaptkhamur-13 commented Apr 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

HansujaB commented Apr 18, 2026 •

edited

Loading