Add epochs_metadata_excludes

[hoechenberger]

This new setting allows for the exclusion of epochs based on metadata.

In theory this is already possible via conditions, but especially with lots of nested event names, this becomes very cumbersome very quickly, because the auto-generated metadata dataframe currently does not create columns for such event groupings. That is, if you have e.g. the following events:

stim/1
stim/2
stim/3
stim/4
stim/5
bad_response

and you want to analyze all stim trials but exclude all epochs that have a bad_response event in the metadata. You cannot simply specify:

conditions = {'stim': 'stim.notna() and bad_response.isna()'}

because there won't be a column 'stim' in the auto-generated metadata. Instead, you'd have to add each event name explicitly, and use backticks to make the forward slashes work:

conditions = {
    'stim':
        '(`stim/1`.notna() or '
        ' `stim/2`.notna() or '
        ' `stim/3`.notna() or '
        ' `stim/4`.notna() or '
        ' `stim/5`.notna()) and'
        'bad_response.isna()'
}

Now imagine doing this with even more conditions … This is not very user friendly.

Also there might be experiments where all participants get to be presented with a stim, but you might have groups that only get to see stim/1 and stim/2, while others only get to see stim/3 and stim/4. You'd have to produce different conditions for each group, as the columns corresponding to the not-presented stimuli would simply be missing, and the query would fail, complaining about missing columns.

With this PR, the above situation can be addressed by simply specifying:

epochs_metadata_excludes = ['bad_response.notna()']
conditions = ['stim']

Before merging …

• Changelog has been updated (docs/source/changes.md)

[agramfort]

couldn't you rather do:

event_name.str.contains('stim/') and bad_response.isna()

or something like this?

[hoechenberger]

couldn't you rather do:

event_name.str.contains('stim/') and bad_response.isna()

or something like this?

This might work, will give it a shot

[hoechenberger]

@agramfort Your proposal works, closing this PR! Thanks!