ENH: Add `description` filter parameter to `Raw.crop_by_annotations()`

Open Beginner friendly
#13,743 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Quiet
Tech stack
python
Domain
data

Research direction

Start in mne/io/base.py at Raw.crop_by_annotations() and compare the existing filtering pattern in mne/annotations.py, especially _select_annotations_based_on_description(). Verify that description=None preserves current behavior while string and list inputs select the requested annotations before cropping; done means both forms work without breaking the default path.

Written by the indexing model from the issue text.

Description

ENH
Describe the new feature or enhancement

Raw.crop_by_annotations()currently crops the raw data for every annotation with no way to filter by description. If a recording has multiple annotation types like "stimulus","bad","response"...there is no way to crop only a specific type without a messy workaround

it would be much cleaner to do...

raws = raw.crop_by_annotations(description="stimulus")
#or multiple types
raws = raw.crop_by_annotations(description=["stimulus", "response"])
Describe your proposed implementation

adding a description parameter to crop_by_annotations() in mne/io/base.py. When description=None (the default), the method behaves exactly as it does today, so there is no API breakage.

when a description is provided, annotations are filtered before cropping...

if description is not None:
    if isinstance(description, str):
        description = [description]
    mask = np.isin(annotations.description, description)
    annotations = annotations[mask]

mne/annotations.py already has a private function_select_annotations_based_on_description() used internally by
events_from_annotations() that does exactly this kind of filtering, so the pattern is already established in the codebase

Describe possible alternatives

users can already work around this manually..

mask = raw.annotations.description == "stimulus"
raw.crop_by_annotations(annotations=raw.annotations[mask])

But this is verbose and inconsistent with how other mne methods handle description filtering. Adding the parameter directly to the method is cleaner and more ergonomic for the common use case

Additional context

No response

Dominant language
Python
Stars
3.5k
Forks
1.6k
Avg merge
1d 6h
Merged PRs (30d)
100

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from mne-tools/mne-python

All issues in mne-tools/mne-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.