Skip to content

DOC: clarify add_reference_channels usage (Takeover #13664)#13846

Open
Dpereaptkhamur-13 wants to merge 8 commits intomne-tools:mainfrom
Dpereaptkhamur-13:doc-ref-channel-clarification
Open

DOC: clarify add_reference_channels usage (Takeover #13664)#13846
Dpereaptkhamur-13 wants to merge 8 commits intomne-tools:mainfrom
Dpereaptkhamur-13:doc-ref-channel-clarification

Conversation

@Dpereaptkhamur-13
Copy link
Copy Markdown

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

@HansujaB
Copy link
Copy Markdown
Contributor

HansujaB commented Apr 18, 2026

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
Copy link
Copy Markdown
Author

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
Copy link
Copy Markdown
Contributor

tsbinns commented Apr 20, 2026

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
Copy link
Copy Markdown
Author

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants