Working with events

This tutorial describes event representation and how event arrays are used to subselect data. :depth: 2

As usual we'll start by importing the modules we need, loading some example data <sample-dataset>, and cropping the :class:~mne.io.Raw object to just 60 seconds before loading it into RAM to save memory:

The tutorial tut-events-vs-annotations describes in detail the different ways of obtaining an :term:Events array <events> from a :class:~mne.io.Raw object (see the section overview-tut-events-section for details). Since the sample dataset <sample-dataset> includes experimental events recorded on :term:stim channel STI 014, we'll start this tutorial by parsing the events from that channel using :func:mne.find_events:

Reading and writing events from/to a file

Event arrays are :class:NumPy array <numpy.ndarray> objects, so they could be saved to disk as binary :file:.npy files using :func:numpy.save. However, MNE-Python provides convenience functions :func:mne.read_events and :func:mne.write_events for reading and writing event arrays as either text files (common file extensions are :file:.eve, :file:.lst, and :file:.txt) or binary :file:.fif files. The example dataset includes the results of mne.find_events(raw) in a :file:.fif file. Since we've truncated our :class:~mne.io.Raw object, it will have fewer events than the events file loaded from disk (which contains events for the entire recording), but the events should match for the first 60 seconds anyway:

When writing event arrays to disk, the format will be inferred from the file extension you provide. By convention, MNE-Python expects events files to either have an :file:.eve extension or to have a file basename ending in -eve or _eve (e.g., :file:{my_experiment}_eve.fif), and will issue a warning if this convention is not respected.

Subselecting and combining events

The output of :func:~mne.find_events above (repeated here) told us the number of events that were found, and the unique integer event IDs present:

If some of those events are not of interest, you can easily subselect events using :func:mne.pick_events, which has parameters include and exclude. For example, in the sample data Event ID 32 corresponds to a subject button press, which could be excluded as:

It is also possible to combine two Event IDs using :func:mne.merge_events; the following example will combine Event IDs 1, 2 and 3 into a single event labelled 1:

Note, however, that merging events is not necessary if you simply want to pool trial types for analysis; the next section describes how MNE-Python uses event dictionaries to map integer Event IDs to more descriptive label strings.

Mapping Event IDs to trial descriptors

So far in this tutorial we've only been dealing with integer Event IDs, which were assigned based on DC voltage pulse magnitude (which is ultimately determined by the experimenter's choices about what signals to send to the STIM channels). Keeping track of which Event ID corresponds to which experimental condition can be cumbersome, and it is often desirable to pool experimental conditions during analysis. You may recall that the mapping of integer Event IDs to meaningful descriptions for the `sample dataset

is given inthis table

in theintroductory tutorial

`. Here we simply reproduce that mapping as an event dictionary:

Event dictionaries like this one are used when extracting epochs from continuous data, and the resulting :class:~mne.Epochs object allows pooling by requesting partial trial descriptors. For example, if we wanted to pool all auditory trials, instead of merging Event IDs 1 and 2 using the :func:~mne.merge_events function, we can make use of the fact that the keys of event_dict contain multiple trial descriptors separated by / characters: requesting 'auditory' trials will select all epochs with Event IDs 1 and 2; requesting 'left' trials will select all epochs with Event IDs 1 and 3. An example of this is shown in a later tutorial.

.. TODO replace above sentence when the relevant tut is ready: An example of this is shown later, in the epoch-pooling section of the epochs-intro-tutorial tutorial.

Plotting events

Another use of event dictionaries is when plotting events, which can serve as a useful check that your event signals were properly sent to the STIM channel(s) and that MNE-Python has successfully found them. The function :func:mne.viz.plot_events will plot each event versus its sample number (or, if you provide the sampling frequency, it will plot them versus time in seconds). It can also account for the offset between sample number and sample index in Neuromag systems, with the first_samp parameter. If an event dictionary is provided, it will be used to generate a legend:

Plotting events and raw data together

Events can also be plotted alongside the :class:~mne.io.Raw object they were extracted from, by passing the Event array as the events parameter of :meth:raw.plot <mne.io.Raw.plot>:

Making equally-spaced Events arrays

For some experiments (such as those intending to analyze resting-state activity) there may not be any experimental events included in the raw recording. In such cases, an Events array of equally-spaced events can be generated using :func:mne.make_fixed_length_events:

By default, the events will all be given the integer Event ID of 1, but you can change that with the id parameter. It is also possible to specify an overlap duration — i.e., if you ultimately want :term:epochs that are 2.5 seconds long, but you want them to overlap by 0.5 seconds, you can specify duration=2.5, overlap=0.5 in the call to :func:~mne.make_fixed_length_events (this will yield the same spacing of events as duration=2, overlap=0).