Add regression-based approach to removing EOG artifacts

[wmvanvliet]

This adds the mne.preprocessing.eog_regression function to regress EOG channels out of other channels. This provides a way to remove eye artifacts without zapping out a complete PCA or ICA component from the data. This could be useful when you don't have many channels.

closes #11028

Todo:

• Test effectiveness of the approach
• Example
• Modify existing tutorial
• Decide on API: single eog_regression function or .fit()/.apply() object.
• Add unit tests
• Update "What's new"

[larsoner]

Can you make a sibling PR to deprecate https://github.com/mne-tools/mne-sandbox/blob/master/mne_sandbox/preprocessing/eog.py#L6 ?

Ignore codespell for now, @drammock is on it

[wmvanvliet]

The example script shows the function in action on the MNE-sample data. For some more thorough evaluation, perhaps https://osf.io/2qgrd/ is better suited. This dataset contains EEG data with the subject performing guided eye movements as well as periods of rest. The idea is that the EOG correction procedure should remove as much signal variation during the eye movements as possible while keeping the resting state data as-is. Here is a script that operates on this dataset: https://gist.github.com/wmvanvliet/8c9bc44d46ebf51a54ea0ef35d97398b

And here are the results of that script:

Both ICA and this new regression approach seem to perform excellent.

[wmvanvliet]

@larsoner If you have time, could you take a look at the picks parameter of this function and the way references are done? I know there have been changes regarding how we do these things, but I haven't been keeping tabs on it and now I'm unsure.

[larsoner]

For some more thorough evaluation, perhaps https://osf.io/2qgrd/ is better suited.

Do you think it's worth adding this as a new mne.datasets dataset and adding to a tutorial?

[cbrnr]

The comparison figures for the external dataset look nice. Can you show which figures the example produces? If they are good enough (i.e. show that regression effectively removes ocular artifacts), then I would not add the new dataset.

[wmvanvliet]

Output from the example script:

[cbrnr]

Indeed the figures from the other dataset demonstrate the effectiveness much better. I do like the regression weight from the example though. Would it be possible to create two similar figures like you showed for the other dataset in the left column (eye blinks before and after removal)?

[wmvanvliet]

Here is the eog_regression function applied to the blinks:

[agramfort]

@wmvanvliet can you share the link to the rendered doc when you have it? 🙏

[cbrnr]

Here is the eog_regression function applied to the blinks:

Nice! Please include this figure in the example!

[wmvanvliet]

For some more thorough evaluation, perhaps https://osf.io/2qgrd/ is better suited.

Do you think it's worth adding this as a new mne.datasets dataset and adding to a tutorial?

If we just stick with plain regression, without implementing fancier techniques such as RAAA or SGEYESUB, then the sample dataset is actually fine I think.

[cbrnr]

@agramfort working on it right now!

[cbrnr]

Great work @wmvanvliet! I have some minor suggestions, after that this is good to go! Thanks a lot for this great addition!

[cbrnr]

Sorry, forgot the example. Only some minor things though.

[agramfort]

good to go from your end ?

[wmvanvliet]

CI not happy yet :(

[cbrnr]

Can you post links to the rendered docs?

[wmvanvliet]

Latest render of the docs:

Tutorial: https://output.circle-artifacts.com/output/job/77cc1118-8f72-4e07-a03c-49fde7bb10f6/artifacts/0/dev/auto_tutorials/preprocessing/35_artifact_correction_regression.html
Example: https://output.circle-artifacts.com/output/job/77cc1118-8f72-4e07-a03c-49fde7bb10f6/artifacts/0/dev/auto_examples/preprocessing/eog_regression.html

[wmvanvliet]

CI pass! All is ready from my end, unless someone has some more nitpicks.

[cbrnr]

You still have raw.apply_proj() in the tutorial, is there a reason why you didn't delete it?

[cbrnr]

Also, these lines in the example should be formatted as code:

I don't have time to go through all things that I mentioned previously, but it would be nice that in case you do not want to implement a comment/suggestion to at least let me know.

[wmvanvliet]

Sorry for being overzealous in marking your comments as resolved. I indeed missed some things. I went over them again and I think I got them all now.

[wmvanvliet]

Updated example, code is now rendering as it should: https://output.circle-artifacts.com/output/job/7861b8ab-d51b-473f-8a37-37ca66c10e3c/artifacts/0/dev/auto_examples/preprocessing/eog_regression.html

[cbrnr]

No problem @wmvanvliet, thanks for going through everything once again!

Re the example, sorry that I keep nitpicking, but I think the line Import packages and load the MNE sample data. should also be a comment as part of the code. So the first code block should start with

# Author: Marijn van Vliet <w.m.vanvliet@gmail.com>

and end with

raw.filter(0.3, None, picks='all')

[wmvanvliet]

That was intentional. Why should that sentence be a comment and not just a paragraph block?

[cbrnr]

That's fine of course, but right now it is not a sentence, that's why I thought it was supposed to be a comment. Can you change it to a proper sentence?

[wmvanvliet]

Done :)

[cbrnr]

Perfect, thanks a lot!

[larsoner]

Thanks @wmvanvliet !