DOC: clarify average EEG reference behavior and update tutorial note by Farzah11 · Pull Request #13664 · mne-tools/mne-python

Farzah11 · 2026-02-17T12:00:37Z

This PR clarifies the behavior of average EEG referencing when the original
reference electrode is not present in the data.

Adds an explicit note to the set_eeg_reference docstring explaining that
the average is computed only over existing EEG channels.
Updates the preprocessing tutorial to explicitly mention using
add_reference_channel when applying an average reference and the original
reference is missing.

Closes #13618

drammock · 2026-02-17T15:16:59Z

mne/_fiff/reference.py

+    channel (or was removed during acquisition or preprocessing), it is not
+    implicitly accounted for in the average.
+    For sensor-space analyses where this distinction matters, consider adding
+    a zero-filled reference channel using :func:`add_reference_channel` before


this will need to be a fully qualified path or else the cross-reference will fail, e.g. :func:`~mne.add_reference_channels`

drammock · 2026-02-17T15:19:40Z

tutorials/preprocessing/55_setting_eeg_reference.py

+# Note:
+# When computing an average reference, if the dataset does not include
+# the original reference electrode, the average will be biased because
+# the missing channel is ignored. To avoid this, first add a
+# zero-valued reference channel using
+# mne.add_reference_channels(). This ensures that
+# all intended channels, including the original reference,
+# contribute correctly to the average.


as written, this will get treated like code comments. To format it like a normal paragraph, it needs # %% as the first line of the block. You could also consider making it a true "note" admonition, using .. note:: as the first line and indenting the rest.

Farzah11 · 2026-02-18T11:39:27Z

Hi @drammock ,

I’ve pushed updates addressing the points you mentioned. I noticed that the build_docs and linkcheck checks are currently failing, Kindly review when convenient. Thank you:)

tsbinns · 2026-02-18T13:03:04Z

@Farzah11 Those checks aren't failing as such, they're just not being run because you don't have an account with CircleCI. If you sign up (and push another commit), they'll run.

drammock · 2026-02-18T15:13:00Z

for now I've manually triggered a re-run.

drammock · 2026-02-18T16:18:52Z

lots of doc build failures: https://app.circleci.com/pipelines/gh/mne-tools/mne-python/30250/workflows/f842ecd6-5a62-44e1-b8be-f23114f9087a/jobs/79140?invite=true#step-143-0_106

@Farzah11 I recommend building docs locally to debug these quicker

behinger · 2026-02-18T21:19:00Z

mne/_fiff/reference.py

+    in the data. If the original reference electrode was not recorded as a
+    channel (or was removed during acquisition or preprocessing), it is not
+    implicitly accounted for in the average.
+    For sensor-space analyses where this distinction matters, consider adding


I think this is not definite enough. Maybe:

This matters for sensor-space analyses: The resulting reference would not be a correct average reference, as the subtracted reference signal would be divided by n-channels and not n-channels + 1 reference channel. Further discussion can be found in Kim et. al 2013 https://doi.org/10.3389/frsip.2023.1064138. Consider adding a ...

Farzah11 · 2026-02-20T03:56:14Z

Thanks for the clarification and for manually re-running the checks.
I’ve just set up CircleCI on my fork and will next revise the wording per the feedback and build the docs locally to address the failures before pushing updates.

- Move average reference note to docs.py (set_eeg_reference_see_also_notes) - Remove floating text from reference.py docstring - Add note to tutorial about using add_reference_channels for correct avg ref - Include Kim et al. (2023) paper reference - Fix line lengths to comply with PEP 8 (<= 79 chars)

Farzah11 · 2026-02-22T21:25:47Z

Hi,

I’ve been investigating the build_docs and linkcheck checks and attempted to reproduce them locally.

From the CircleCI page, it appears the jobs are currently blocked with block-unregistered-user, so the documentation build has not actually executed yet.

Could a maintainer please approve or rerun the CircleCI workflow for this PR when convenient?

Thank you.

CarinaFo · 2026-02-22T23:52:31Z

Hi,

I’ve been investigating the build_docs and linkcheck checks and attempted to reproduce them locally.

From the CircleCI page, it appears the jobs are currently blocked with block-unregistered-user, so the documentation build has not actually executed yet.

Could a maintainer please approve or rerun the CircleCI workflow for this PR when convenient?

Thank you.

Hi Farzah,

Could you explain what went wrong during your attempt at running the documentation locally?

I had some issues on the weekend with building docs on a windows 11 server in python 3.11, so I might be able to help.

Please also let us know if the documentation is unclear or missing something.

Thank you for contributing,

Carina

Farzah11 · 2026-02-23T04:39:53Z

Hi Carina,

I built the docs locally on Windows 11 / Python 3.11 using make html and make linkcheck, and didn’t encounter a hard Sphinx error locally.

At the moment I’m not seeing a specific CI failure yet, as the CircleCI jobs appear to be blocked with block-unregistered-user, so the docs build doesn’t actually run or produce logs.

Once the checks are approved and run, I should be able to see any concrete errors and debug them properly.

Thanks for the offer to help.

tsbinns · 2026-02-23T10:30:48Z

@Farzah11 Please see this comment and make an account with CircleCI so that the jobs don't need to be manually triggered by us each time: #13664 (comment)

But there is an issue with the changed docstring, as shown by this test failure: https://github.com/mne-tools/mne-python/actions/runs/22285364149/job/64470384061?pr=13664

Farzah11 · 2026-02-25T03:44:44Z

Hi, I’ve created a CircleCI account as suggested.

The CI jobs are still blocked with block-unregistered-user, so I believe my GitHub account needs to be approved for CircleCI on the MNE-Python side.

@drammock Could you please approve my GitHub account for CI so the jobs can run automatically?

In parallel, I’m fixing the docstring-related test failure shown in the GitHub Actions log and will push an update shortly.

Thanks!

tsbinns · 2026-02-25T09:53:53Z

The CI jobs are still blocked with block-unregistered-user, so I believe my GitHub account needs to be approved for CircleCI on the MNE-Python side.

@Farzah11 You need to push a commit (even an empty one) to trigger another CI run.

Farzah11 · 2026-03-05T22:08:48Z

Hi @drammock,

I’ve addressed the earlier feedback and updated the wording accordingly.
All CI checks and documentation builds are now passing.

Please let me know if any further changes are needed. Thanks for the review!

drammock

Something is off with CircleCI, it's showing successful doc build, but the run only lasted 5 seconds and there's no artifact attached. Hopefully whatever is causing this will resolve itself by the time you've made the suggested changes below.

drammock · 2026-03-05T23:06:30Z

doc/changes/dev/13664.doc.rst

+Clarify in the documentation that :func:`mne.add_reference_channels`
+should be used before :func:`mne.set_eeg_reference` with
+``ref_channels="average"`` when the original reference electrode
+is missing.


take a look at other changelog entries in this folder, and follow the conventions seen there (e.g., include your name at the end as a link). If you're not in doc/changes/names.inc yet, add yourself there too.

drammock · 2026-03-05T23:09:17Z

mne/utils/docs.py

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

+    For sensor-space analyses, if the original reference electrode is not
+    present as a channel, the resulting average reference is biased because


Suggested change

present as a channel, the resulting average reference is biased because

present as a channel, the resulting average reference will be biased because

(you may need to reflow the text, this might push the line to be too long, didn't check)

drammock · 2026-03-05T23:10:32Z

mne/utils/docs.py

+    (including the reference). For a correct average reference, add a
+    zero-filled reference channel with :func:`~mne.add_reference_channels`
+    before calling :func:`~mne.set_eeg_reference`. For further discussion,
+    see Kim et al. (2023, doi:10.3389/frsip.2023.1064138).


search our codebase for :footcite: and :footbibliography: to see how we handle references. You'll need to add Kim et al 2023 to our BibTeX file for it to work.

drammock · 2026-03-05T23:11:32Z

tutorials/preprocessing/55_setting_eeg_reference.py

 raw_avg_ref = raw.copy().set_eeg_reference(ref_channels="average")
 raw_avg_ref.plot()

+# .. note::


Suggested change

# .. note::

# %%

# .. note::

without this, I don't think the admonition will render correctly --- it will just get treated like a block of code comments

DOC: clarify average EEG reference behavior and update tutorial note

76687f2

Farzah11 requested review from agramfort and drammock as code owners February 17, 2026 12:00

drammock reviewed Feb 17, 2026

View reviewed changes

behinger reviewed Feb 18, 2026

View reviewed changes

Farzah11 force-pushed the fix-eeg-reference-doc branch from dec3ef8 to f44ea8f Compare February 22, 2026 20:32

DOC: Use footcite for paper reference and add to references.bib

868960b

Farzah11 requested a review from larsoner as a code owner February 22, 2026 20:54

DOC: Use plain text citation instead of footcite

fe3841c

Add changelog entry for EEG reference documentation

a8e92a3

drammock reviewed Mar 5, 2026

View reviewed changes

	present as a channel, the resulting average reference is biased because
	present as a channel, the resulting average reference will be biased because

Uh oh!

Conversation

Farzah11 commented Feb 17, 2026

Uh oh!

drammock Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

drammock Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Farzah11 commented Feb 18, 2026

Uh oh!

tsbinns commented Feb 18, 2026

Uh oh!

drammock commented Feb 18, 2026

Uh oh!

drammock commented Feb 18, 2026

Uh oh!

behinger Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Farzah11 commented Feb 20, 2026

Uh oh!

Farzah11 commented Feb 22, 2026

Uh oh!

CarinaFo commented Feb 22, 2026

Uh oh!

Farzah11 commented Feb 23, 2026

Uh oh!

tsbinns commented Feb 23, 2026

Uh oh!

Farzah11 commented Feb 25, 2026

Uh oh!

tsbinns commented Feb 25, 2026

Uh oh!

Farzah11 commented Mar 5, 2026

Uh oh!

drammock left a comment

Choose a reason for hiding this comment

Uh oh!

drammock Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

drammock Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

drammock Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

drammock Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants