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

This comment was not addressed. Please address this before resolving it.

fix: correct typo in docs.py Co-authored-by: Thomas S. Binns <t.s.binns@outlook.com>

doc: reformat reference channel note for clarity Co-authored-by: Thomas S. Binns <t.s.binns@outlook.com>

Dpereaptkhamur-13 · 2026-05-01T05:21:31Z

I've updated the changelog filename to 13846.other.rst and included the :newcontrib: tag with my name. I also alphabetized the bibliography and removed the extra blank lines in channels.py. Everything should be ready for a final review!

tsbinns

@Dpereaptkhamur-13 Thanks for the changes, but there were some comments which were not adressed. Please address these now, as well as some final additional things.

tsbinns · 2026-05-03T10:48:56Z

+@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},
+  doi = {10.3389/frsip.2023.1064138},
+  volume = {3},
+  pages = {1064138}
+  doi = {10.3389/frsip.2023.1064138},
+}


This citation needs to come after the % everything else comment. Right now, it will interfere with the rendering of the bibtex for the MNE-C package citation.

The DOI field is duplicated, so one of them needs to be removed.

The author information is still not correct.

I have addressed the final three points:
*Moved the citation to immediately after the % everything else comment.
*Removed the duplicate DOI field.
*Corrected the author information to the official citation format.
Everything should be in place now. Thank you for the guidance!

tsbinns · 2026-05-03T10:52:40Z

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


This comment was not addressed. Please address this before resolving it.

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`. Co-authored-by: Thomas S. Binns <t.s.binns@outlook.com>

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

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

Dpereaptkhamur-13 and others added 6 commits May 1, 2026 09:56

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

7319a6d

Update mne/utils/docs.py

a2eb16c

fix: correct typo in docs.py Co-authored-by: Thomas S. Binns <t.s.binns@outlook.com>

Update mne/utils/docs.py

d6839bb

doc: reformat reference channel note for clarity Co-authored-by: Thomas S. Binns <t.s.binns@outlook.com>

DOC: remove blank lines

cbb0596

DOC: fix citation details and alphabetize bibliography

0d98056

MAINT: update changelog name and text

87cd94f

tsbinns requested changes May 3, 2026

View reviewed changes

Dpereaptkhamur-13 and others added 6 commits May 3, 2026 19:03

DOC: fix bibliography location, authors, and duplicate DOI

2b24fca

DOC: fix indentation in tutorial note

2f33978

Update doc/changes/dev/13846.other.rst

6e49874

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`. Co-authored-by: Thomas S. Binns <t.s.binns@outlook.com>

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

2549205

MAINT: add Deep Kaur to names.inc

ec318e6

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

03a3501

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

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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Dpereaptkhamur-13 commented May 1, 2026

Uh oh!

tsbinns left a comment

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

HansujaB commented Apr 18, 2026 •

edited

Loading