ERPLAB Studio: EVENTLIST Structure - ucdavis/erplab GitHub Wiki

This page describes the EventList structure, which lies at the core of ERPLAB. First, we would like to provide an overview of the processes leading up to averaging to help you see the big picture. The basic steps are as follows:

• Extract a list of the event codes from the EEG data in a dataset and store it in an EventList structure. This list may then be edited to add, delete, and/or modify the events (e.g., to add responses from your stimulus presentation system, to add eye movement onsets from an eye tracker, to delete spurious event codes, etc.). The manual page for Creating an EventList provides details of creating an EventList.
• You can also export the EventList to a text file or .xls file, edit it, and import it back into the EEG dataset or into an ERPset (see documentation here).
• Using the events stored in the EventList structure, determine which events will be assigned to each bin. This is usually accomplished with the BINLISTER routine.
• Convert the continuous EEG into a set of fixed-duration epochs, time-locked to the relevant events in the EventList structure.
• Apply artifact detection routines to mark epochs that should be excluded from averaging. The epochs are not deleted; they are simply marked in the EventList and then excluded from averaging in the next stage.
• Average together the epochs for each bin, creating an ERP structure (which is stored in an ERPset).
• Perform behavioral analyses on the data stored in the EventList, possibly excluding events with artifacts so that the behavioral analyses reflect the same trials as the ERP waveforms. Other processes may be interposed between these steps. For example, one could filter the data after epoching but before artifact rejection.

ERPLAB provides a great deal of power and flexibility in these steps. To harness this power, you really need to understand the EventList structure. You may be tempted to just skim this section; if you do, be sure to come back later to read this information carefully. In the long run, you will save time (and aggravation!) by understanding the underlying logic and details of how ERPLAB works.

Sophisticated ERP experiments often involve complex sequences of events (stimuli, responses, EMG bursts, eye movements), and the event information stored by EEGLAB in the EEG structure is insufficient (or too difficult to access) for the analysis of many ERP experiments. ERPLAB has thus created the EventList structure to allow this information to be stored and manipulated in a convenient manner.

For each event, the EventList has a record indicating the event code, its time of occurrence, its duration, a set of 8 binary artifact flags that indicate whether an artifact was present for that event (and the nature of the artifact), and a set of 8 binary user flags that can be used to code anything that the user would like to represent about an event (e.g., whether the subject was in a state of high alpha, what task the subject was performing at the time of the event, etc.). It can be very convenient to have this information stored separately from the EEG data (e.g., for behavioral analyses), and the EventList structure can be saved as a text file or .xls file as well as being appended onto the relevant EEG structure (which allows it to be saved and loaded along with the EEG structure). You can edit the exported file with Matlab's text editor or a spreadsheet program and then reload it, causing it to overwrite the original set of events in the dataset. This provides a mechanism for adding, deleting, and modifying events. Of course, you can also directly modify the EventList structure by writing a Matlab script.

Note for ERPSS users: There is no "condition code" concept in ERPLAB, but user flags within the EventList can be used to emulate this concept.

The EventList contains a copy of all the event information stored in the type field of the EEG structure, plus information about events that have been marked for artifact rejection in the reject field of the EEG structure, along with several additional pieces of information that will be described later. It is important to realize that EEGLAB doesn't "know" anything about the EventList structure. Consequently, a little bit effort is sometimes needed to make sure that any changes you make to the EventList structure get copied back into the EEG.event and EEG.reject structure and any changes you make to these parts of the EEG structure get copies back into the EventList structure. Any ERPLAB routines that modify the event codes in the EventList structure will ask you if you want to copy the modified events back into the EEG.event structure. You can also do this manually by going to the EventList panel and clicking Transfer event info to EEG.event.

Similarly, when the Artifact Detection panel is used to mark epochs containing artifacts, the EEG.reject structure will automatically be updated. The artifact information in EEG.reject and in the EventList structure can also be synchronized manually by going to the Artifact Info & Tools panel and clicking Syn. artifact info in EEG and EventList.

One key limitation of the EEG.event structure is that each event can be identified by a numeric event code or a text label, but you cannot have both. ERPLAB allows you to have both in the EventList structure. That way you can assign a text label for each numeric event code without losing the original numeric event codes (and vice versa).

Eventually you will convert your continuous EEG data into a set of discrete epochs, time-locked to the events in the EEG structure. When you do this, many of the events from the continuous EEG will not be time-locking events (e.g., response event codes will not be used as time-locking events if you are time-locking to stimulus events). However, the EventList structure will continue to maintain all of the events. This is important because artifact detection is performed on the epoched data, and you may want to exclude trials with artifacts from your behavioral analyses. The EventList structure makes this possible because it contains all of the information about your stimuli and responses and can also contain information about which events were rejected because of artifacts.

You can see the EventList by going to the EventList panel and clicking View. Here's what the EventList looks like for a simple oddball experiment.

At the top of the window, you can see some general information about the EEGset (which is not present in the EventList itself). It indicates the name of the dataset from which the EventList was created, the sampling rate, the number of events, etc.

The next section of the window shows a list of the events. The first column is the item number. This number is not stored in the EventList structure, but is simply the position of the event within the EventList.

The next column shows the epoch number (labeled bepoch to indicate that this is based on ERPLAB's bin-based epoching routine). In a continuous dataset, the epoch number is always listed as 0. The bepoch number in the EventList indicates the epoch within the epoched datafile for which the current event was the time-locking event. Any events in the EventList that are not time-locking events within the epoched datafile have a bepoch value of 0. In the oddball experiment shown here, for example, there are event codes for each stimulus and each response, but we would have epochs only for the stimuli (assuming that we are making stimulus-locked ERPs). However, the response events are still shown in the EventList so you know they existed at one point.

The next two columns are the numeric event code (ecode) and the text label (label) for the event. Each event must have at least one of these two values to indicate what kind of event it was, and the BINLISTER routine that is used to assign events to bins requires numeric event codes. Some EEG acquisition programs provide labels, and others provide numeric codes. ERPLAB's routine for creating the EventList provides a simple function that can add labels based on the numeric codes or can add numeric event codes based on the text labels.

The next three columns provide timing information. The onset time is the most important column, because it indicates when the event code began (in seconds, relative to the beginning of the file). The diff column indicates the amount of time in milliseconds between the current event and the previous event; it is there for your information only (i.e., changing this value will not change the time of the event). The dura column provides the duration of the event. Some EEG acquisition systems provide real information about an event's duration (e.g., how long a button was held down). ERPLAB does not currently use this information, but it is available for future expansion (and can be accessed by custom Matlab scripts).

The next column is a set of 8 binary user flags, each of which can have a value of 0 or 1. These can be used for any purpose, but they are most commonly used to keep track of information used when the events are sorted into bins by BINLISTER.

The user flags are followed by a set of artifact flags, which are set by ERPLAB's artifact detection routines. The rightmost of these (flag 1) indicates whether ERPLAB has detected an artifact for that event, and the others (flags 2-8) can be used to indicate what kind of artifact was detected.

ERPLAB's artifact detection routines will also set values in EEG.reject so that rejected epochs are displayed in a special color. EEGLAB has additional artifact detection routines, and it also allows you to manually mark or unmark epochs for rejection. However, this does not automatically set the appropriate flags in the EventList structure (because EEGLAB doesn't "know" anything about the EventList structure). Also, if you manually change the artifact flags in the EventList structure (e.g., with a script or by editing a text version of the EventList structure), these changes will not be automatically propagated to EEG.reject. In these cases, you can synchronize the information in the EventList flags and in EEG.reject using the Artifact Info & Tools panel. In addition, when you create averaged ERPs, ERPLAB will automatically check for any differences between the EventList flags and EEG.reject; if it detects any differences, it will give you the opportunity to synchronize before averaging.

• Note for programmers*: The artifact flags and user flags are stored together in a single integer variable, with the least significant byte being used for the artifact flags and the most significant byte being used for the user flags.

The next column is an enable value, which is used to indicate whether the event should be used or ignored by any routines that operate on the EventList structure. For example, if the subject was asleep or an electrode was disconnected for a period of 20 events, this value could be set to zero for those events, and those events would be ignored during averaging. The same effect could be obtained by simply deleting the events from the EventList, but using the enable flag allows the events to be "turned back on" at a later point if desired. Currently, the enable value can be modified only by writing a Matlab script that modifies the EventList or by exporting the EventList as a text or .xls file, modifying it, and importing it.

The final column is the bin field, which is used to determine which bin the event will be assigned to during the averaging process. In a simple oddball experiment, for example, Bin 1 might be the standard stimuli and Bin 2 might be the target stimuli. The bin assignment is ordinarily accomplished with the BINLISTER routine. However, you can also assign bins by writing a Matlab script or by exporting the EventList as a text or .xls file, modifying it, and importing it. Note that a given event might not be assigned to any bin (as in the response events in the example shown above). In addition, a given event can be assigned to more than one bin (e.g., a target event could be assigned into a "Correctly Detected Targets" bin and also into an "All Targets" bin).

You can also view the contents of an EventList structure directly from the Matlab command line by typing EEG.EventList (followed by Enter or Return).