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

[aman-coder03]

Reference issue (if any)

fixes #13743

What does this implement/fix?

Raw.crop_by_annotations() currently crops the raw data for every annotation with no way to filter by description. This PR adds an optional description parameter that lets you crop only annotations with matching descriptions
example:

# crop only stimulus annotations
raws = raw.crop_by_annotations(description="stimulus")

# or multiple types at once
raws = raw.crop_by_annotations(description=["stimulus", "response"])

when description=None (the default), the method behaves exactly as before, so there is no API breakage...
filtering uses np.isin on the annotation descriptions, which follows the same pattern as _select_annotations_based_on_description already used internally in mne/annotations.py.

Additional information

• added a test test_crop_by_annotations_description in mne/io/tests/test_raw.py
• parametrized over meas_date and first_samp to match the existing test_crop_by_annotations style
• fully backward compatible, description=None is the default

[PragnyaKhandelwal]

Hey @aman-coder03, I tested your branch locally to see how it handles some edge cases. The base implementation looks good, but I found some things that might be worth refining to match with MNE standards

I noticed you mentioned _select_annotations_based_on_description in the issue but didn't use it in the PR. I ran a test (see below) and found that using the manual np.isin logic misses out on Regex support, which MNE users generally expect when filtering by description. Was there a specific reason you decided to move away from the helper function?
Currently, the filtering is strictly case-sensitive. The internal helper might provide more flexibility here like we have the rules in the events_from_annotations.
If a user provides a description that doesn't exist (like a typo), the method returns an empty list silently. Would it be worth adding a logger.warning so the user knows why they got no results?

[aman-coder03]

thanks for the review, i investigated _select_annotations_based_on_description but it expects an event_id dict rather than a description list, so it's not the right tool here.
i have kept np.isin for exact matching and added a RuntimeWarning when no annotations match. Regex and case-insensitivity could be a follow-up enhancement...

[PragnyaKhandelwal]

Thanks for the update, @aman-coder03! Adding that RuntimeWarning will definitely help users catch typos in their filters. I see your point about the helper function being a bit more aligned with the event_id workflow. I'll leave it to the maintainers to decide if they want to stick with exact matching for now or if they'd prefer the full Regex/Case flexibility provided by the internal helpers.