Document EEG reference

We keep getting questions of users that are confused with MNE’s EEG referencing behavior. This is not surprising, as the documentation does not cover this topic. At the very least, we need to add a note that for EEG data, a reference must be specified at all times. If the user does nothing, MNE will add an average reference. If another reference is desired, the user should use the mne.io.set_eeg_reference function to specify this.

[Edit by Eric89GXL: also, need to add a tutorial]

[larsoner]

This is really a dup of #3410, but I’ll close that one since this one has a richer discussion.

Both of these are almost a dup of #2727, which highlights how we have done some inconsistent things with add_egg_ref for a long time.

I agree with @agramfort (now) that we should add a method. But I would go a step further and make it the only way to add an EEG reference. It’s more pythonic than having add_eeg_ref args, sometimes defaulting to True, sporadically placed in our code – which is what we have now. So I’d actually really prefer deprecating all add_eeg_ref args. Perhaps more importantly, it forces people to be more explicit about when the average reference gets added. We already have safeguards against inversion without average ref, so we should be safe to do this.

[agramfort]

+1 to add such documentation. Any suggestion where?

also the more I get questions about EEG reference the more I feel that:

mne.io.set_eeg_reference

is not easy to find and the io module is clearly not a naturally place to look.

2 options:

• move mne.io.set_eeg_reference to mne.set_eeg_reference
• add a set_eeg_reference method to the data containers. I know I was opposed to this to keep the number of methods low but it’s true that it’s a quite general use case…