ENH: adds annotation filtering to raw and ica source figures

[DerAndereJohannes]

This pull request is a correction to the pull request #13425 where I accidently messed up the merge. I felt it was more simple to just open a new one.

Below is the copy/paste of the initial description that I had:

---

Reference issue

Looking to solve issue #13325. Thank you to @larsoner for allowing me to go ahead with this enhancement.

What does this implement/fix?

This feature looks to add a convenience parameter in the plot function to automatically hide annotation labels that we are currently not interested in. For example, if we have a dataset that uses the ECG R peak as a response, this might make the stimulus triggers more difficult to see and slows down moving around the dataset due to additional computational cost.

To mitigate this, this pull request looks at adding a annotation_regex parameter which takes a regex as input and includes any matching annotation label in the view and hides the rest (default .* for all annotations).

The current version of this feature changes the current fig.mne.visible_annotations variable from setting True to everything, to setting True to only those annotation labels that fit the annotation_regex parameter.

This was the most logical place to put it as it deals with the initialization of fig.mne.visible_annotations, works with both qt and matplotlib backends and does not change the behaviour of the actual browser when you use it.

Additional information

I have set this pull request to be a draft, as I have just implemented the bare minimum to create the feature to see if where I am editing the code is implemented well. There is currently no documentation (Though this would be a quick add).

Example Code using the new feature

import mne

BACKEND = "qt" # "matplotlib"

mne.viz.set_browser_backend(BACKEND)

# Example dataset included in the mne repository
raw = mne.io.read_raw_brainvision("mne/io/brainvision/tests/data/test.vhdr")

raw.plot(block=True, annotation_regex="^Stimulus")

Example Images

All Triggers in a Matplotlib Browser

Triggers with Parameter annotation_regex="^Stimulus" in a Matplotlib Browser

Triggers with Parameter annotation_regex="^Stimulus" in a QT Browser

Let me know if I can supply anything else or if I am ok to add the documentation regarding the current code and change this to an actual pull request.

Thanks in advance!

closes #13325

[DerAndereJohannes]

It looks like my attempts at referencing functions in the doc change is what is causing the build to fail:

/home/circleci/project/doc/<rst_prolog>:55: WARNING: py:obj reference target not found: annotation_regex [ref.obj]
/home/circleci/project/doc/<rst_prolog>:55: WARNING: py:func reference target not found: mne.viz.raw.plot_raw [ref.func]
/home/circleci/project/doc/<rst_prolog>:55: WARNING: py:func reference target not found: mne.viz.ica.plot_sources [ref.func]

Exited with code exit status 1

any suggestion on how to fix this would be greatly appreciated.

Thank you again for your patience!

[tsbinns]

@DerAndereJohannes To fix the docs failing to build:

1. Double ticks `` should be used to render annotation_regex as code. With single ticks, sphinx will treat this as an object it needs to find a link for.
2. The function names you want to link to are mne.viz.plot_raw and mne.viz.plot_ica_sources.

It might also be worth adding a link to the methods mne.io.Raw.plot and mne.preprocessing.ICA.plot_sources where the new parameter is also supported. Just keep in mind that these require the :meth: tag.

[DerAndereJohannes]

Thank you for the help and explaining the functionality around sphinx! I really appreciate it. I have made the changes and added your recommendation to the file.

[larsoner]

@tsbinns feel free to merge if you're happy

The changelog entry CI is failing for unrelated reasons, something with our TOML being problematic now

[tsbinns]

@larsoner I don't have those permissions for the main repo, just mne-connectivity.

[larsoner]

@larsoner I don't have those permissions for the main repo, just mne-connectivity.

Now you should!

[larsoner]

I'll merge main into this branch once #13436 lands then it should come back green @tsbinns

[tsbinns]

Had a look through and I'm happy with the changes.

I'll merge main into this branch once #13436 lands then it should come back green @tsbinns

Was gonna say, I can only enable auto-merge. Thanks!

[tsbinns]

Forgot to say earlier, but thanks @DerAndereJohannes!