Events

Events#

Main#

events_create()#

events_create(event_onsets, event_durations=None, event_labels=None, event_conditions=None)[source]#

Create events dictionnary from list of onsets

Parameters:

  • event_onsets (array or list) – A list of events onset.

  • event_durations (array or list) – A list of durations. If none is passed, will take the duration between each onset (i.e., will assume that events are consecutive).

  • event_labels (list) – A list containing unique event identifiers. If None, will use the event index number.

  • event_conditions (list) – An optional list containing, for each event, for example the trial category, group or experimental conditions.

Returns:

dict – Dict containing 3 or 4 arrays, "onset" for event onsets, "duration" for event durations, "label" for the event identifiers and the optional "conditions" passed to event_conditions.

See also

events_plot, events_to_mne, events_find

Example

In [1]: import neurokit2 as nk

In [2]: events = nk.events_create(event_onsets = [500, 1500, 2500, 5000])

In [3]: events
Out[3]: 
{'onset': [500, 1500, 2500, 5000],
 'duration': array([ 500, 1000, 1000, 2500]),
 'label': array(['1', '2', '3', '4'], dtype='<U11')}

In [4]: events = nk.events_create(event_onsets = [500, 1500, 2500, 5000],
   ...:                           event_labels=["S1", "S2", "S3", "S4"],
   ...:                           event_conditions=["A", "A", "B", "B"])
   ...: 

In [5]: events
Out[5]: 
{'onset': [500, 1500, 2500, 5000],
 'duration': array([ 500, 1000, 1000, 2500]),
 'label': ['S1', 'S2', 'S3', 'S4'],
 'condition': ['A', 'A', 'B', 'B']}

events_find()#

events_find(event_channel, threshold='auto', threshold_keep='above', start_at=0, end_at=None, duration_min=1, duration_max=None, inter_min=0, discard_first=0, discard_last=0, event_labels=None, event_conditions=None)[source]#

Find Events

Find and select events in a continuous signal (e.g., from a photosensor).

Parameters:

  • event_channel (array or list or DataFrame) – The channel containing the events. If multiple channels are entered, the channels are handled as reflecting different events new channel is created based on them.

  • threshold (str or float) – The threshold value by which to select the events. If "auto", takes the value between the max and the min. If "auto" is used with multi-channel inputs, the default value of 0.9 is used to capture all events.

  • threshold_keep (str) – "above" or "below", define the events as above or under the threshold. For photosensors, a white screen corresponds usually to higher values. Therefore, if your events are signaled by a black colour, events values are the lower ones (i.e., the signal “drops” when the events onset), and you should set the cut to "below".

  • start_at (int) – Keep events which onset is after a particular time point.

  • end_at (int) – Keep events which onset is before a particular time point.

  • duration_min (int) – The minimum duration of an event to be considered as such (in time points).

  • duration_max (int) – The maximum duration of an event to be considered as such (in time points).

  • inter_min (int) – The minimum duration after an event for the subsequent event to be considered as such (in time points). Useful when spurious consecutive events are created due to very high sampling rate.

  • discard_first (int) – Discard first or last n events. Useful if the experiment starts with some spurious events. If discard_first=0, no first event is removed.

  • discard_last (int) – Discard first or last n events. Useful if the experiment ends with some spurious events. If discard_last=0, no last event is removed.

  • event_labels (list) – A list containing unique event identifiers. If None, will use the event index number.

  • event_conditions (list) – An optional list containing, for each event, for example the trial category, group or experimental conditions. This option is ignored when multiple channels are supplied, as the function generates these automatically.

Returns:

dict – Dict containing 3 to 5 arrays, "onset" for event onsets, "duration" for event durations, "label" for the event identifiers, the optional "condition" passed to event_conditions and the events_channel if multiple channels were supplied to the function.

See also

events_plot, events_to_mne, events_create

Example

Simulate a trigger signal (e.g., from photosensor)

In [1]: import neurokit2 as nk

In [2]: import numpy as np

In [3]: signal = np.zeros(200)

In [4]: signal[20:60] = 1

In [5]: signal[100:105] = 1

In [6]: signal[130:170] = 1

In [7]: events = nk.events_find(signal)

In [8]: events
Out[8]: 
{'onset': array([ 20, 100, 130]),
 'duration': array([40,  5, 40]),
 'label': array(['1', '2', '3'], dtype='<U11')}

In [9]: nk.events_plot(events, signal)
../_images/p_events_find1.png

The second event is an artifact (too short), we can skip it

In [10]: events = nk.events_find(signal, duration_min=10)

In [11]: nk.events_plot(events, signal)
../_images/p_events_find2.png

Combine multiple digital signals into a single channel and its compute its events The higher the channel, the higher the bit representation on the channel.

In [12]: signal2 = np.zeros(200)

In [13]: signal2[65:80] = 1

In [14]: signal2[110:125] = 1

In [15]: signal2[175:190] = 1

In [16]: nk.signal_plot([signal, signal2])

In [17]: events = nk.events_find([signal, signal2])

In [18]: events
Out[18]: 
{'onset': array([ 20,  65, 100, 110, 130, 175]),
 'duration': array([40, 15,  5, 15, 40, 15]),
 'events_channel': array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.,
        0., 0., 0., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
        1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
        1., 1., 1., 1., 1., 1., 1., 1., 1., 0., 0., 0., 0., 0., 2., 2., 2.,
        2., 2., 2., 2., 2., 2., 2., 2., 2., 2., 2., 2., 0., 0., 0., 0., 0.,
        0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 1., 1.,
        1., 1., 1., 0., 0., 0., 0., 0., 2., 2., 2., 2., 2., 2., 2., 2., 2.,
        2., 2., 2., 2., 2., 2., 0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1.,
        1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
        1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
        0., 0., 0., 0., 0., 2., 2., 2., 2., 2., 2., 2., 2., 2., 2., 2., 2.,
        2., 2., 2., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]),
 'condition': [1, 2, 1, 2, 1, 2],
 'label': array(['1', '2', '3', '4', '5', '6'], dtype='<U11')}

In [19]: nk.events_plot(events, events["events_channel"])
../_images/p_events_find3.png ../_images/p_events_find4.png

Convert the event condition results its human readable representation

In [20]: value_to_condition = {1: "Stimulus 1", 2: "Stimulus 2", 3: "Stimulus 3"}

In [21]: events["condition"] = [value_to_condition[id] for id in events["condition"]]

In [22]: events
Out[22]: 
{'onset': array([ 20,  65, 100, 110, 130, 175]),
 'duration': array([40, 15,  5, 15, 40, 15]),
 'events_channel': array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.,
        0., 0., 0., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
        1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
        1., 1., 1., 1., 1., 1., 1., 1., 1., 0., 0., 0., 0., 0., 2., 2., 2.,
        2., 2., 2., 2., 2., 2., 2., 2., 2., 2., 2., 2., 0., 0., 0., 0., 0.,
        0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 1., 1.,
        1., 1., 1., 0., 0., 0., 0., 0., 2., 2., 2., 2., 2., 2., 2., 2., 2.,
        2., 2., 2., 2., 2., 2., 0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1.,
        1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
        1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
        0., 0., 0., 0., 0., 2., 2., 2., 2., 2., 2., 2., 2., 2., 2., 2., 2.,
        2., 2., 2., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]),
 'condition': ['Stimulus 1',
  'Stimulus 2',
  'Stimulus 1',
  'Stimulus 2',
  'Stimulus 1',
  'Stimulus 2'],
 'label': array(['1', '2', '3', '4', '5', '6'], dtype='<U11')}

events_plot()#

events_plot(events, signal=None, color='red', linestyle='--')[source]#

Visualize Events

Plot events in signal.

Parameters:

  • events (list or ndarray or dict) – Events onset location. Can also be a list of lists, in which case it will mark them with different colors. If a dict is passed (e.g., from events_find()), it will only plot the onsets.

  • signal (array or DataFrame) – Signal array (can be a dataframe with many signals).

  • color (str) – Argument passed to matplotlib plotting.

  • linestyle (str) – Argument passed to matplotlib plotting.

Returns:

fig – Figure representing a plot of the signal and the event markers.

See also

events_find

Examples

In [1]: import neurokit2 as nk

In [2]: nk.events_plot([1, 3, 5])
../_images/p_events_plot1.png

  • Example 1: With signal

In [3]: signal = nk.signal_simulate(duration=4)

In [4]: events = nk.events_find(signal)

In [5]: nk.events_plot(events, signal)
../_images/p_events_plot2.png

  • Example 2: Different events

In [6]: events1 = events["onset"]

In [7]: events2 = np.linspace(0, len(signal), 8)

In [8]: nk.events_plot([events1, events2], signal)
../_images/p_events_plot3.png

  • Example 3: Conditions

In [9]: events = nk.events_find(signal, event_conditions=["A", "B", "A", "B"])

In [10]: nk.events_plot(events, signal)
../_images/p_events_plot4.png

  • Example 4: Different colors for all events

In [11]: signal = nk.signal_simulate(duration=10)

In [12]: events = nk.events_find(signal)

In [13]: events = [[i] for i in events['onset']]

In [14]: nk.events_plot(events, signal)
../_images/p_events_plot5.png

events_to_mne()#

events_to_mne(events, event_conditions=None)[source]#

Create MNE-compatible events

Create MNE compatible events for integration with M/EEG.

Parameters:

  • events (list or ndarray or dict) – Events onset location. Can also be a dict obtained through events_find().

  • event_conditions (list) – An optional list containing, for each event, for example the trial category, group or experimental conditions. Defaults to None.

Returns:

tuple – MNE-formatted events and the event id, that can be added via raw.add_events(events), and a dictionary with event’s names.

See also

events_find

Examples

In [1]: import neurokit2 as nk

In [2]: signal = nk.signal_simulate(duration=4)

In [3]: events = nk.events_find(signal)

In [4]: events, event_id = nk.events_to_mne(events)

In [5]: events
Out[5]: 
array([[   1,    0,    0],
       [1001,    0,    0],
       [2001,    0,    0],
       [3001,    0,    0]])

In [6]: event_id
Out[6]: {'event': 0}

# Conditions
In [7]: events = nk.events_find(signal, event_conditions=["A", "B", "A", "B"])

In [8]: events, event_id = nk.events_to_mne(events)

In [9]: event_id
Out[9]: {'A': 0, 'B': 1}