Epoch exclusion based on timing in to_epochs

[gongcastro]

Summary

I wrote a small function to exclude certain events from df_stim when running to_epochs.

This would allow the user to exclude certain epochs that, despite their trial type being included in trial_types, overlap with some other events that make the epoch undesirable. For instance, if triggers were sent online during the task indicating events like noise, external interference, etc., the user may want to exclude epochs overlapping with such events.

Below I explain the rationale, happy to clarify or adjust the code to ease integration if the PR is considered.

How it works

0. This is the original df_stim:

# trial_types "E" mark undesirable events
df_stim = pd.DataFrame(
    {
        "onset": [0.5, 1.3, 2.6, 4.1, 4.5, 4.7],
        "duration": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
        "value": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
        "trial_type": ["A", "E", "A", "E", "B", "E"],
    }
)
print(df_stim)

	onset	duration	value	trial_type
0	0.5	1.0	1.0	A
1	1.3	1.0	1.0	E
2	2.6	1.0	1.0	A
4	4.5	1.0	1.0	B
5	4.7	1.0	1.0	E

1. The user provides a list of trial types to be excluded via the exclude_trial_types argument in to_epochs.

epochs = to_epochs(
    timeseries,
    df_stim,
    ["A", "B"],
    before=0.3 * units.s,
    after=1 * units.s,
    exclude_trial_types=["E"],
)

2. If this argument is not None and not empty, the function exclude_events removes from df_stim any events for which:
   a) Trial type is included in exclude_trial_types
   b) At least one subsequent event with onset between onset-before and onset+after has trial type included in exclude_trial_types

if exclude_trial_types:
    df_stim = exclude_events(df_stim, exclude_trial_types, before, after)

In the example, the resulting intermediate version of df_stim only includes the third event, as it is the only that does not satisfy (a) and (b). The function exclude_events can also be called outside of to_epochs to simply exclude the corresponding events beforehand:

df_new = exclude_events(df_stim, exclude_trial_types, before, after)
print(df_new)

	onset	duration	value	trial_type
2	2.6	1.0	1.0	A

Testing

I added additional tests for exclude_events and for the modified version of to_epochs (testing the behaviour of the new argument). The whole testing suit runs fine locally.

Note: not sure which branch to direct this PR, sending it to main until told otherwise.

PS: Thanks for your work! Cedalion is working very well in our lab (dealing with messy newborns data).