Clarify that a ValueError is raised when doing inverse modeling without a average rereference projector ready

[nabilalibou]

Proposed documentation enhancement

Issue discussed on the forum: https://mne.discourse.group/t/average-reference-as-projector-is-recommended-for-inverse-modeling-in-documentation-but-is-in-fact-mandatory/8224

Issue observed

According to the documentation: Setting the EEG reference — MNE 1.6.1 documentation 1

It is written that:

when performing inverse imaging, MNE-Python will raise a ValueError if there are EEG channels present and something other than an average reference strategy has been specified.

But in fact, having an average rereference applied on the data before doing inverse modeling will raises an error. To not raise an error, the data object need to have an average rereference projector ready (not applied). It could be nice to clarify this as I have been surprised by an error with the "Custom EEG reference is not allowed for inverse modeling." after my data went through my preprocessing pipeline containing an average rereference step (applied because i have custom epoch rejection algorithms).

Proposed documentation enhancement

Do you think simply clarify what raises the error in the doc paragraph is sufficient or a trick to divert the problem might be interesting to add ? Like doing set_eeg_reference(ref_channels='average', projection=True) just before resolving the inverse problem even if you already applied a ref.

[welcome[bot]]

Hello! 👋 Thanks for opening your first issue here! ❤️ We will try to get back to you soon. 🚴

[larsoner]

Yes, adding something like "consider calling inst.set_eeg_reference(projection=True) to add an average reference projector" would be good. PR welcome if you're willing to give it a shot @nabilalibou !

[nabilalibou]

Ok, i will take care of it