Document that add_reference_channel should be used with set_eeg_reference for average reference

[behinger]

Proposed documentation enhancement

Hey!
We (mostly @jschepers) might have diagnosed an issue in MNE:

• We often want to have a different reference e.g. average reference in EEG.
• But also often, the reference channel is not included in the data-set (because it is flat / removed during recording etc.).

Then, when naively applying the average reference with set_eeg_reference, one can very easily get the wrong result, as the calculation in mne boils down to (we think, the projection-code makes tracing the actual calculation difficult to us):
sum(over_channels) / n_channels

• "ignoring" the forgotten reference channel, and not
  sum(over_channels) / (n_channels+1) - including the "forgotten" reference channel.

The (for us) seemingly correct way to calculate average reference is to add_reference_channel before, then calculating the average reference (optional: drop the reference channel again for fullrank data).

We assumed, MNE does this by default, but we were wrong. We think this could be documented, that if the reference channel is not included in the data, one should add_reference_channel before calculating average reference.

We think for a user this is a super easy mistake to do, and indeed, in e.g. eeglab the "wrong" reference was calculated for many years as well (in 2017 the new function fullRankAveRef was added, see https://eeglab.ucsd.edu/wiki/Makoto%27s_preprocessing_pipeline "Why should we add zero-filled channel before average referencing? (10/31/2025 Updated"))

We are happy to provide some example code if necessary to understand. We can also propose some documentation in the tutorial + reference-function. One could also think to check if a reference channel is included in the data (we don't know how), and if not - either calculate sum(...)/(n+1). or add a channel prior to re-referencing, or throw a warning

We hope we didn't miss anything too obvious! Thanks a ton for the hard work.

Cheers, Bene & Judith

[larsoner]

I haven't thought much about this issue, but have a couple of quick thoughts. First the practice of including the zeroed-out channel differs across manufacturers / formats -- to take two that come to mind immediately:

1. Neuromag EEG / .fif -- the electrode is typically on the nose and serves as the reference, but there is no channel for it in the data. You could in principle add a zero-filled channel for it, apply the avg reference as you say, etc., but in practice nobody does this.
2. EGI MFF -- the electrode that serves as a reference is added as a channel in the data that is all zeros.

For projectors, we take them into account this reference electrode properly during forward / inverse calculation etc. (its contribution is subtracted out... even though it will cancel later during avg ref proj) so I think things are okay in those pipelines. And for sensor analysis, projectors always bias the data slightly (hence the proj="reconstruct" option in evoked.plot), avg ref projectors included. (For source-space analyses, this bias is compensated for by applying the same projector to the forward model that you do to the data.) So I think in the case of an average reference projector, things behave as expected, and we maybe need to document things better somewhere. I'm guessing this was a conscious choice during development of Neuromag pipelines to treat EEG this way, knowing the end goal is source imaging...

But for sensor-space analyses without using / understanding / accepting projector bias, when people do set_eeg_reference(ref_channels="average", projection=False) (which is the default!) I suspect the n vs n+1 bug is probably in there. At the very least we should document it, and suggest that people add a reference channel if it's missing and they intend to rely on sensor-space analyses.