Native Filtering of Annotations when plotting

[DerAndereJohannes]

Describe the new feature or enhancement

Motivation: I have a dataset with many annotations. When I plot this dataset with all of the annotations (~ 10,000), the figure response terribly slow with changes only happening after every 5 seconds. I believe this is because of the annotation quantity in the plot and the rendering of all the vertical lines at the bottom of the display. When I remove the annotations and plot that i.e., raw.copy().set_annotations(None).plot() then the figure response without any issue and it is easy to use.

I was hoping that the events parameter (i.e., raw.plot(events = None)) would have the same effect as the snippet above, but this just plots the entire annotation object anyway. This means that there is no simple way of just looking at a few important annotations that I am interested in other than defining a subset of annotations, setting the annotations in the Raw to that annotations object and then plotting e.g.,:

backup = d2a.annotations

desired_description = "Stimulus"
mask = np.array([desired_description in desc for desc in backup.description])

subset = mne.Annotations(
    onset=backup.onset[mask],
    duration=backup.duration[mask],
    description=backup.description[mask],
    orig_time=backup.orig_time
)

d2a.set_annotations(subset)

d2a.plot(block = True)

d2a.set_annotations(backup)

Describe your proposed implementation

The main issue is in the plotting function and that it cannot handle the number of annotations efficiently. I would then like to propose to add a parameter to the plot(). I would like something similar to what already exists in the events_from_annotations method here: https://github.com/mne-tools/mne-python/blob/main/mne/annotations.py#L1840-L1843 . E.g., I would like to do the following:

raw.plot(annotation_regex = "^Stimulus")

This would allow us to skip filtering the annotations ourselves and allows us to concentrate on the exact stimulus we want to see.

Describe possible alternatives

This could alternatively be done by directly filtering the annotations through the Raw object. E.g.,

raw.filter_annotations(regex = "^Stimulus")

raw.plot()

Which could then also be used in the plot function afterwards. This implementation might be nicer if you are working with annotations a lot without visualization, but I believe the other solution is better as we are still keeping all of the annotations and just filtering them for the visualization.

Additional context

No response

[larsoner]

To me the annotation_regex=".*" probably makes the most sense here since this is pretty plotting specific, and also would also work well with how we allow changing events just for plotting. Doing raw.filter_annotations I think could be accomplished better with operating on the annotations in arbitrary ways then using raw.set_annotations etc.

One interesting complication would be if you set this to something and then in mne-qt-browser create a new annotation that does not match the regex... so maybe we should warn people to be careful using annotation_regex if they plan to interactively create annotations in the browser.

@DerAndereJohannes would you be interested in opening a PR to add annotation_regex to raw.plot?

[DerAndereJohannes]

Hi larsoner, thank you for your feedback.

I agree with your comments with adding it in the plot function, as the regex would primarily be just for visual inspection.

I can make an attempt at implementing the changes where I will also take a closer look at how to handle the live annotating function. Should I ping you in the PR when I create it?

[larsoner]

Should I ping you in the PR when I create it?

Sure!