ENH: adds annotation filtering to raw figures

[DerAndereJohannes]

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!

[welcome]

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

[larsoner]

Looks reasonable. Can you add a test? Or even better, modify an existing test (to save on testing time) and make sure that the set of annotations is indeed limited compared to the default show-all. And yes you can add doc/changes/devel/13425.newfeature.rst with the :newcontrib: role and a new entry in doc/changes/names.inc!

[larsoner]

Suggested change

	annotation_regex=".*",
	*,
	annotation_regex=".*",

[larsoner]

If you're going to add it here (which is reasonable) we need to make everything kwarg-only (which we've been doing to functions bit-by-bit)

Suggested change

	annotation_regex=".*",
	*,
	annotation_regex=".*",

[larsoner]

This and everything afterward should be passed as keywords like annotation_regex=annotation_regex,

[DerAndereJohannes]

Thank you very much for the fast response! I have applied the changes you have mentioned and added some sample tests. I have added the tests to the already existing test_plot_annotations, though I have also added additional invokations to creating a figure with plot. I decided to add an additional invokation to test the default (.*) as I wanted to do it on something that had at least 2 annotations. The second test filters out one of them. such that one of them is true and the other is false.

Let me know if I should make any additional changes to the documentation or if I should convert this to a real pull request.

Thanks!

Edit:
With the failed tests, it seems like the function I changed with coloring the annotations is also used by the ICA and other plotting functions. Should I also add annotation_regex to these functions along with their tests? I think the feature makes most sense in just the raw plot, but adding it to the others would give similar behaviour among plotting.

[larsoner]

With the failed tests, it seems like the function I changed with coloring the annotations is also used by the ICA and other plotting functions. Should I also add annotation_regex to these functions along with their tests? I think the feature makes most sense in just the raw plot, but adding it to the others would give similar behaviour among plotting.

Sure feel free to add it there! Would be nice for user consistency I think