Skip to content

DOC: clarify average EEG reference behavior and update tutorial note #13664

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Farzah11 wants to merge 5 commits into
base: main
Choose a base branch
from
Open

DOC: clarify average EEG reference behavior and update tutorial note #13664

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
76687f2
DOC: clarify average EEG reference behavior and update tutorial note
Farzah11 Feb 17, 2026
f44ea8f
DOC: Fix average reference documentation structure
Farzah11 Feb 22, 2026
868960b
DOC: Use footcite for paper reference and add to references.bib
Farzah11 Feb 22, 2026
fe3841c
DOC: Use plain text citation instead of footcite
Farzah11 Feb 22, 2026
a8e92a3
Add changelog entry for EEG reference documentation
Farzah11 Mar 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions doc/changes/dev/13664.doc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
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.
Copy link
Copy Markdown
Member

@drammock drammock Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

1 change: 1 addition & 0 deletions mne/_fiff/reference.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -404,6 +404,7 @@ def set_eeg_reference(
Array of reference data subtracted from EEG channels. This will be
``None`` if ``projection=True``, or if ``ref_channels`` is ``"REST"`` or a
:class:`dict`.

%(set_eeg_reference_see_also_notes)s
"""
from ..forward import Forward
Expand Down
8 changes: 8 additions & 0 deletions mne/utils/docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4103,6 +4103,14 @@ 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']``.
For sensor-space analyses, if the original reference electrode is not
present as a channel, the resulting average reference is biased because
Copy link
Copy Markdown
Member

@drammock drammock Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

the subtracted signal is divided by n channels instead of n + 1
(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).
Copy link
Copy Markdown
Member

@drammock drammock Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- 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']``.
Expand Down
8 changes: 8 additions & 0 deletions tutorials/preprocessing/55_setting_eeg_reference.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,14 @@
raw_avg_ref = raw.copy().set_eeg_reference(ref_channels="average")
raw_avg_ref.plot()

# .. note::
Copy link
Copy Markdown
Member

@drammock drammock Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

# 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 :func:`mne.add_reference_channels`. This ensures
# that all intended channels, including the original reference, contribute
# correctly to the average.

# %%
# .. _section-avg-ref-proj:
#
Expand Down
Loading