Improve ica.plot_overlay on Raw instances

[mscheltienne]

Fixes #11805
Using ica.plot_overlay on a raw will now open one figure per channel type, with 2 panes for EEG and MEG data. The second pane now shows the GFP or the RMS instead of the channel average.
When used on evoked, the figure is already split by channel type and I don't think it's worth adding GFP/RMS for evoked responses. The difference in the overlay should be clear enough.

[larsoner]

Can you touch some tutorial (make some trivial change to line breaks, wording, etc.) that uses this code so we can see the effect in CircleCI? Hopefully the main ICA tutorial would do it...

[mscheltienne]

Tutorial render: https://output.circle-artifacts.com/output/job/dc11834c-eb32-4ab2-8cc9-25ae21c727dd/artifacts/0/html/auto_tutorials/preprocessing/40_artifact_correction_ica.html#looking-at-the-ica-solution

MWE if you want to check on combined M/EEG data:

from mne.datasets import sample
from mne.io import read_raw_fif
from mne.preprocessing import ICA


fname = sample.data_path() / "MEG" / "sample" / "sample_audvis_raw.fif"
raw = read_raw_fif(fname, preload=False)
raw.crop(tmin=0, tmax=10).pick(["meg", "eeg"])
raw.load_data()
raw.filter(1.0, 40.0)

ica = ICA(n_components=0.95, method="picard", max_iter=10)
ica.fit(raw)
ica.exclude = [0, 1, 2]
ica.plot_overlay(raw)

[drammock]

Tutorial render: https://output.circle-artifacts.com/output/job/dc11834c-eb32-4ab2-8cc9-25ae21c727dd/artifacts/0/html/auto_tutorials/preprocessing/40_artifact_correction_ica.html#looking-at-the-ica-solution

comparing the MAG plot versus main it seems like we have less useful result now (where EEG is better). Maybe we should do:

• EEG: GFP
• MAG: average
• GRAD: RMS

?

[larsoner]

I think in principle MAG could have the same cancellation problems as EEG where a polarity reversal averaged across all channels (e.g., negative in left hemi and positive in right) could make an artifact look smaller than it is. So even though in this example the ECG for example looks less ECG-like, it seems safer in principle

[mscheltienne]

We could have a third pane for MAGs with the average. It's true that in this case the average is more informative than the RMS, but as for EEG it will be very case dependent.

[larsoner]

We could have a third pane for MAGs with the average. It's true that in this case the average is more informative than the RMS, but as for EEG it will be very case dependent.

Would it be too complex to have the average shown as well as long as it's not EEG-with-an-average-ref? Like show it for mags, grads, eeg-without-average-ref, etc.

[mscheltienne]

Sure, I can add back the average except if custom_ref_applied is ON, but this is not a guarantee of the presence or lack of average reference. There is no knowledge of what the EEG reference is.
Maybe also a warning if the average values yielded are very small, e.g. e-18 range and below?

[larsoner]

Sure, I can add back the average except if custom_ref_applied is ON

I was thinking you would check if there was an average ref projector and not show in that case. The custom_ref_applied could mean stuff like bipolar referencing, not just average ref.

Maybe also a warning if the average values yielded are very small, e.g. e-18 range and below?

I guess we could... but I think as long as we show the STD, the mean being near-zero should make sense if your ref was avg. Users in principle shouldn't be surprised by this

[mscheltienne]

Yes, custom_ref_applied is too restrictive while the average ref projector is not restrictive enough.
Options for a third subplot on top of the butterfly plot and of the GFP (eeg)/RMS (mag/grad):

1. Average except for EEG with custom_ref_applied. It could be a different ref than a CAR, and it does not guarantee that a CAR is not applied, e.g. if a user creates a raw from a numpy array with a CAR applied.
2. Average except for EEG with an average ref projector. At least when the projector is present, we know for sure what the reference is. But a CAR could still be applied if the projector is absent.
3. Average except for EEG channels. IMO, GFP is more informative.

I slightly prefer option (3), restore the average plot for all channel types except EEG. But no strong opinion, any preference?

[larsoner]

I'm fine with (3) or (2). The advantage of (2) is it's a bit more backward-compatible -- people can see the same information they've had previously. So I think I'm +1 on (2) and + 0.5 on (3)

[mscheltienne]

(2) done, good to go on my side.
Render: https://output.circle-artifacts.com/output/job/5c6b50e2-f7c8-451a-adc1-222c8fbb0a7a/artifacts/0/html/auto_tutorials/preprocessing/40_artifact_correction_ica.html#repairing-artifacts-with-ica

From the tutorial:

[larsoner]

So in:

https://mne.tools/dev/auto_tutorials/preprocessing/40_artifact_correction_ica.html#repairing-artifacts-with-ica

You can see the average over EEG is non-zero. This suggests it should be shown on this PR. So maybe the check that makes it not be shown needs to be "has average ref and it has been applied to the data" rather than just "has average ref".

[mscheltienne]

Oops, I'll fix that 🙈

[drammock]

looks pretty good! thanks for tackling this. A few minor suggestions/comments below.

[mscheltienne]

Render: https://output.circle-artifacts.com/output/job/c0c9b234-fb14-43bc-83a1-6f3511ac1b72/artifacts/0/html/auto_tutorials/preprocessing/40_artifact_correction_ica.html#sphx-glr-auto-tutorials-preprocessing-40-artifact-correction-ica-py