mne.find_events¶

mne.find_events(raw, stim_channel=None, verbose=None, output='onset', consecutive='increasing', min_duration=0, shortest_event=2, mask=0)¶

Find events from raw file

Parameters:

raw : Raw object

The raw data.

stim_channel : None | string | list of string

Name of the stim channel or all the stim channels affected by the trigger. If None, the config variables ‘MNE_STIM_CHANNEL’, ‘MNE_STIM_CHANNEL_1’, ‘MNE_STIM_CHANNEL_2’, etc. are read. If these are not found, it will fall back to ‘STI 014’ if present, then fall back to the first channel of type ‘stim’, if present.

verbose : bool, str, int, or None

If not None, override default verbose level (see mne.verbose).

output : ‘onset’ | ‘offset’ | ‘step’

Whether to report when events start, when events end, or both.

consecutive : bool | ‘increasing’

If True, consider instances where the value of the events channel changes without first returning to zero as multiple events. If False, report only instances where the value of the events channel changes from/to zero. If ‘increasing’, report adjacent events only when the second event code is greater than the first.

min_duration : float

The minimum duration of a change in the events channel required to consider it as an event (in seconds).

shortest_event : int

Minimum number of samples an event must last (default is 2). If the duration is less than this an exception will be raised.

mask : int

The value of the digital mask to apply to the stim channel values. The default value is 0.

Returns:

events : array, shape = (n_events, 3)

All events that were found. The first column contains the event time in samples and the third column contains the event id. For output = ‘onset’ or ‘step’, the second column contains the value of the stim channel immediately before the the event/step. For output = ‘offset’, the second column contains the value of the stim channel after the event offset.

See also

find_stim_steps: Find all the steps in the stim channel.

Examples

Consider data with a stim channel that looks like: [0, 32, 32, 33, 32, 0]

By default, find_events returns all samples at which the value of the stim channel increases:

>>> print(find_events(raw)) 
[[ 1  0 32]
 [ 3 32 33]]

If consecutive is False, find_events only returns the samples at which the stim channel changes from zero to a non-zero value:

>>> print(find_events(raw, consecutive=False)) 
[[ 1  0 32]]

If consecutive is True, find_events returns samples at which the event changes, regardless of whether it first returns to zero:

>>> print(find_events(raw, consecutive=True)) 
[[ 1  0 32]
 [ 3 32 33]
 [ 4 33 32]]

If output is ‘offset’, find_events returns the last sample of each event instead of the first one:

>>> print(find_events(raw, consecutive=True, 
...                   output='offset'))
[[ 2 33 32]
 [ 3 32 33]
 [ 4  0 32]]

If output is ‘step’, find_events returns the samples at which an event starts or ends:

>>> print(find_events(raw, consecutive=True, 
...                   output='step'))
[[ 1  0 32]
 [ 3 32 33]
 [ 4 33 32]
 [ 5 32  0]]

To ignore spurious events, it is also possible to specify a minimum event duration. Assuming our events channel has a sample rate of 1000 Hz:

>>> print(find_events(raw, consecutive=True, 
...                   min_duration=0.002))
[[ 1  0 32]]

For the digital mask, it will take the binary representation of the digital mask, e.g. 5 -> ‘00000101’, and will block the values where mask is one, e.g.:

'0000111' <- trigger value
'0100101' <- mask
----------------
'0000010'