The EVENTLIST structure

The big picture

This section 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.).

á       Using the events stored in the EVENTLIST structure, determine which events will be assigned to each bin.  This is accomplished using the BINLISTER routine.

á       Convert the continuous EEG in the dataset 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 excluded from averaging in the next stage.

á       Average together the epochs for each bin, creating an ERP structure (which is stored in a new 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.  However, these steps are usually conducted in this order without any interposed operations.

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.

What is the EVENTLIST for?

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 and why it was rejected, 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 as well as being appended onto the relevant EEG structure (which allows it to be saved and loaded along with the EEG structure). It is created from the current EEG structure. If you save the EVENTLIST as a text file, you can edit it with a text editor (or a program created in Matlab or some other language) 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. 

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, information about events that have been marked for artifact rejection in the reject field of the EEG structure, plus 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, some effort is necessary 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 with the ERPLAB > Transfer eventinfo to EEG.type command.  Similarly, when the ERPLAB > Artifact Detection routines are used to find artifacts, the EEG.reject structure will automatically be updated, and the artifact information in EEG.reject and in the EVENTLIST structure can also be synchronized automatically with the ERPLAB > Artifact Detection > Synchronize Artifact Info in EEG and EVENTLIST command (note: this has not yet been implemented).

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 canÕt 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 (see the section on epoching).  When you do this, many of the events from the continuous EEG will be lost (e.g., response 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.  We have added a piece of information to the EEG structure that allows ERPLAB to know which event in the EVENTLIST structure corresponds to the time-locking event in each epoch in the EEG structure (more details will be provided in the section on behavioral analyses).  In addition, the EVENTLIST structure includes an EVENTLIST.eventinfo.bepoch field that stores the event number of an event after epoching.

Creating an EVENTLIST

You must create an EVENTLIST structure for a given dataset to use it with ERPLAB. This is usually done on the continuous EEG data, prior to using any ERPLAB routines to process the dataset.  An EventList can be created from the current dataset in two ways.  The simplest is to use ERPLAB > EventList > Create EventList (simple).  This just creates the EVENTLIST structure from the information in the EEG.event structure.

The second way to create an EventList is to use ERPLAB > EventList > Create EventList (advanced), which brings up the window shown below.  This version allows you to assign a text label to each event code, and you can also use it to assign event codes to bins (if there is a simple 1:1 mapping between event codes and bins).  If your data acquisition system uses text labels instead of numeric event codes for each event (e.g. EGI), you could assign a numeric event code to each label and/or assign each event label to a bin.

Note: ERPLAB does not yet make full use of event labels, so you will likely need numeric event codes.

 

The example shown in the screenshot above is from a simple oddball experiment in which the standard stimulus corresponds to an event code of 122, the target corresponds to an event code of 112, target responses correspond to an event code of 9, and standard responses correspond to an event code of 8.  Each occurrence of the target is assigned to Bin 1 (labeled Òtarget binÓ) and each occurrence of the standard is assigned to Bin 2 (labeled Òstandard binÓ).  The response event codes were not assigned to any bin.  To set up this mapping, a table was created (shown in the left portion of the window).

To assign event labels to your event codes (or vice versa), you begin by using the GUI to build a table in which each line specifies one type of event, giving the event code and event label for that event type (and, optionally, a bin number and bin description).  Once you have built the table and click APPLY, the program will find each event matching the event code and add the corresponding label in the EVENTLIST.eventinfo structure (or vice versa if you have event labels but not event codes).  If you do not provide a label for a given event code, the event code will still appear in the EVENTLIST.eventinfo structure.  In addition, if you provide bin information, the EVENTLIST structure will contain bin assignments for each event for which a bin has been defined.  It is fine if some events are not assigned to a bin (e.g., the response events in the screenshot above).

The table is created as follows.  When you begin, the only line in the table (shown in the left portion of the window) will be new line, and it will be highlighted.  You can then enter an event code, an event label, and bin number, and a bin description in the right portion of the window.  You then click on update line and it will create a line in the table with that event code, event label, bin number, and bin description.  The bin number and bin description are optional; in most cases, you will not assign bins at this stage (the typical method is described in the next section).  The screen shot shows how the window looks after several events have been described.  To edit a line, simply click on it and update the values for that line; you must then click update line to update the values in the current line.

Once you have created the table, you must save it as a file (this will allow you to use it again, either for the same dataset or for a different dataset from another subject).  To do this, simply click save list.  To open a previously saved list, simply click open list.  Once you have the list, you can create the EVENTLIST structure by clicking the UPDATE button.  You can easily create this list with a text editor (such as the Matlab editor) instead of using the Create Eventlist GUI; if you use the GUI to create a simple table, you will readily see the format for this table.

There are two important options. The first is Create EventList text file output.  Selecting this option (and specifying a filename) will save a copy of the EVENTLIST structure in a text file.  In the next section, we will take a look at the contents of an EventList text file, which will give you a better idea of what information is stored in the EVENTLIST structure.  Note that if you donÕt save the EventList as a file at this point, you can do it later by selecting ERPLAB > EventList > Export EventList to Text File.

The second option is Transfer EVENTLIST info to EEG.event.  You will usually want to do this, because it gives you the ability to use the text labels you have just created for each event code when viewing the EEG in EEGLABÕs plotting functions (e.g., Plot > Channel data scroll).  If you select this option, it will cause another window to pop up (after you click APPLY).  This window is shown in the screenshot to the left.  It allows you to choose whether the event info in the EEG structure will contain the numeric event codes, the code labels, or the bin labels for each event (which then determines how event codes are labeled when you plot the data).  You will usually want to select Code Labels.  The two screenshots below show what the EEG will look like when you view it with the original event codes (top screenshot) and with the event labels (bottom screenshot).  Note that a limited amount of space is provided by EEGLAB for showing the labels, so it is usually best to have relatively short labels (10 characters or less).

Note: A special version of the Plot > Channel data (scroll) routine must be installed in EEGLAB, or else you will be able to see only 3-4 characters of your labels.  The procedure for this is described in the Installation section of this manual.

Instead of event codes or event labels, you can choose to store Bin Labels in the EEG structure.  This alternative applies only after you have assigned events to bins (either at this stage or by means of the BINLISTER routine at a later stage).  The bin label is a string that indicates the bin to which the epoch has been assigned.  The original event label or event is also provided (in parentheses) for your information.  For example, if an event code of 100 was assigned to Bin 1, the bin label for this event code would be changed to B1(100).  If a given event code is assigned to multiple bins, the bins are separated by commas.  That is, if an event code of 100 was assigned to Bins 1 and 7, the label for this event code would be changed to B1,7(100).  If event labels are present, they are used inside of the parentheses instead of event codes (e.g.,  B1,7(target)).

Note: We will eventually make it possible to use event labels in addition to event codes when using BINLISTER to assign events to bins.  However, this has not yet been implemented, so the main use of event labels at present is during viewing of the raw EEG data.

The Contents of an EVENTLIST

To understand the contents of an EventList, it is easiest to consider what the EventList looks like when saved to a text file.  Here is an example of a text-file version of an EVENTLIST, showing the first six events in a simple oddball experiment.

bin 1,    # 252,        Standard (correct)                                                                                 

bin 2,    # 63,           Target (correct)       

                                                                           

#item    bepoch     ecode        label                 onset          diff                dura          b_flags           a_flags                enable     bin

#                                                                                     (sec)            (sec)            (msec)     (binary)           (binary)

1             0                    122              standard        8.0000      0.0000      0.0             00000000   00000000        1                  [ 1 ]

2             0                    9                    std_resp       8.3962      0.3962      0.0             00000000   00000000        1                  [    ]

3             0                    122              standard        10.0000   1.6038      0.0             00000000   00000000        1                  [ 1 ]

4             0                    9                    std_resp       10.4265   0.4265      0.0             00000000   00000000        1                  [    ]

5             0                    132              target              12.0000   1.5735      0.0             00000000   00000000        1                  [ 2 ]

6             0                    9                    targ_resp      12.5191   0.519         0.0             00000000   00000000        1                  [    ]

 

The file begins with a header (described later and not shown here) that 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 file lists the bins for the file (we will say more about where this information comes from in a later section), along with the number of occurrences of each bin in the file (e.g., Ò# 252Ó means that there were 252 occurrences of this bin).

The next two lines are comments (any line beginning with a Ò#Ó is a comment); these comments are labels for the columns that follow.

Each of the following lines represents the information from an event, in order of occurrence.  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 bepoch number.  In a continuous dataset, the epoch is always listed as 0.  Once a datafile has been epoched, only a subset of the event codes remain in the datafile, but all of the events are retained in the EVENTLIST (e.g., response event codes may no longer be present after epoching).  To be able to determine which epoch in the datafile corresponds to a given event in the EVENTLIST, the EVENTLIST stores the epoch number of the event.  More precisely, the bepoch number is 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 an bepoch number of 0.

The next two columns are the event code and label for the event.  Each event must have at least one of these two values to indicate what kind of event it was.  Labels are easier to remember than numbers, and we encourage you to use them.  Some EEG acquisition programs provide labels, but most provide only numeric codes.  ERPLAB provides a simple function that can add labels based on the numeric codes.

The next three columns provide timing information.  The onset time is the most important column, because it indicates when the event code began (relative to the beginning of the file).  The ÒdiffÓ column indicates the amount of time 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.  For example, if you have two conditions (e.g., attend red and attend green), you could use the user flags to indicate what task the subject was doing at the time of each event.

The user flags are followed by a set of artifact flags.  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.

Note: The artifact flags are set by ERPLABÕs artifact detection routines.  These routines will also set values in EEG.reject so that rejected epochs are displayed in a special color by EEGLABÕs plotting routines.  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 with the ERPLAB > Artifact Detection > Synchronize Artifact Info in EEG and EVENTLIST command (note: this has not yet been implemented).  In addition, when you create averaged ERPs using ERPLAB > Compute 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. 

The final column is a Ò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 can be accomplished when the EventList is first created (as described in the previous section), or it can be accomplished using the BINLISTER routine (described in the BINLISTER section).  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).

The header section of an EventList text file looks like this:

#  Non-editable header begin --------------------------------------------------------------------------------

#

#  data format...............: continuous

#  setname...................: S1_Chan_elist

#  filename..................: none_specified

#  filepath..................: none_specified

#  nchan.....................: 16

#  pnts......................: 1069520

#  srate.....................: 500

#  nevents...................: 2557

#  generated by (bdf)........:

#  generated by (set)........: S1_Chan_elist

#  reported in ..............:

#  prog Version..............: 1.1.721

#  creation date.............: 18-Jan-2010 07:43:40

#  user Account..............:

#

#  Non-editable header end --------------------------------------------------------------------------------

 

The following information is provided:

á       The type of dataset: continuous or epoched

á       The name of the dataset from which the EventList was created

á       The name of the dataset that was created along with the EventList (if any)

á       The location of your saved dataset, if you chose to save your dataset

á       The number of channels in your dataset

á       The number of data points in your dataset

á       The sampling rate at which your data was recorded

á       The number of recorded event codes in your dataset

á       The name of the bin descriptor file (if any)

á       The version of ERPLAB that was used to create the EventList

á       The date that the EventList file was created

á       The user account of the person who created the file (if available)

 

Note that the header is not editable.  That is, the header is ignored when you import it back into ERPLAB, so any changes you make to it will have no effect.

You can also view the contents of an EVENTLIST structure directly from the Matlab command line by typing EEG.EVENTLIST.  HereÕs an example:

á                >> EEG.EVENTLIST

á                 

á                ans =

á                 

á                         setname: 'S1_Chan_elist'

á                          report: ''

á                         bdfname: [1x104 char]

á                            nbin: 2

á                         version: '1.1.725'

á                         account: 'luck'

á                        username: ''

á                    trialsperbin: [1009 242]

á                          elname: [1x145 char]

á                             bdf: [1x2 struct]

á                          eldate: '24-Jan-2010 15:59:00'

á                       eventinfo: [1x2557 struct]

á                 

The information about the individual events is in EEG.EVENTLIST.eventinfo, which is an array of sub-structures (one per event).  The fields in EEG.EVENTLIST.eventinfo are as shown in the example below.  Each of the fields in the text file has an obvious analog in the structure, except that the spoint field in the structure is not found in the text file.  This field stores the sample point number (i.e., how many sample points have occurred since the beginning of the file).  The time of the sample is computed from this value, in conjunction with the sampling rate (which is stored in EEG.EVENTLIST.info.srate).  The bini (bin index) field is an array of the bins to which the event has been assigned (if any).  As described above, the item field indicates the item number of the event within the EVENTLIST (event #1, event #2, etc.), and the epoch field indicates the epoch number of the event within the datafile (when the event is the time-locking event within an epoch).

á                ans =

á                 

á                1x2557 struct array with fields:

á                    item

á                    code

á                    binlabel

á                    codelabel

á                    time

á                    spoint

á                    dura

á                    flag

á                    enable

á                    bini

 

The EEG.EVENTLIST structure also contains several pieces of information that are filled by the BINLISTER routine, including the name of the bin descriptor file (stored in bdfname) and a list of the actual bin descriptors (stored in bdf).  This can help you figure out how a file was created when you come back to it at a later time.  The bdf field also contains reaction time information, when extracted by BINLISTER.

Editing and Importing an EventList

A particularly important aspect of the EVENTLIST structure is that events can be modified and then read back into the current dataset, replacing the previous event code information in the EEG structure.  This makes it possible to add to your dataset information about stimuli, responses, physiological variables, or anything else that is not available from the event codes that were originally stored in the EEG file.  For example, studies of motor processing often include EMG recordings, and the EVENTLIST structure makes it easy to convert EMG bursts in the EEG structure into event codes that can be used for EMG-locked averaging.  It can also be used to merge events from a stimulus presentation system into the EEG structure.  For example, the data file created by a stimulus presentation program might have information about responses that is not directly available in the EEG data file, and the EVENTLIST structure provides a conduit for adding this information into a dataset.  We plan to eventually include scripts for reading event information from Presentation and E-Prime data files directly into the EVENTLIST structure; at this point, you would need to write a custom script for this.

There are two basic ways to modify the events in a dataset.  First, one can directly modify the EVENTLIST structure (either from the Matlab command line or from a custom Matlab script).  After youÕve done this, you may wish to run the ERPLAB > Transfer eventinfo to EEG.type command (or itÕs script equivalent) so that EEGLAB functions will have access to the new event information.  Note that this will completely overwrite the previous event information; but thatÕs OK, because you should have all of the original event information in the EVENTLIST structure before you modify it.

The second way to modify the events is to save the EventList as a text file.  You can then edit this file with a text editor (such as the Matlab editor). For example, if you gave the subject the wrong instructions for a portion of the data collection period, you could edit the EventList File to change the enable value to zero for the relevant event codes. Similarly, you could use a text editor to perform a global search-and-replace to modify a particular event code value.  You could also manually enter boundary events in this manner.  If you need to do something more complicated, you could read the EventList text file into a program (in Matlab or some other programming environment), modify it, and then save the output in a new text file.  After modifying the text file, you can read it back into the EVENTLIST structure for the current dataset with the ERPLAB > EventList > Import EventList from Text File command. 

Important note: The header information at the beginning of an EventList text file should not be edited.  Any changes you make to this information will be ignored when the EventList file is read back into ERPLAB.

Here is a detailed description of how you would import the events from a modified EventList text file back into ERPLAB:

á       After editing the EventList file, make sure you save it before proceeding.

á       In the EEGLAB window, choose   ERPLAB > EventList > Import EventList from Text File

á       A window will appear asking you to select the EventList file you wish to feed into ERPLAB.  Choose the newly edited version of your EventList File and click ÔOpenÕ.

á       A confirmation message will appear asking, ÒDo you want to replace your EEG.event field with this file?Ó.  Choose ÔYesÕ.

á       The next window that appears asks you to name the new dataset you have created by importing your new EventList File with all of the new event information.  You must name the dataset.  You also have the option of saving the new dataset to your computer, overwriting the current dataset in memory, etc.

á       Once you have chosen the appropriate combination of options, click ÔOkÕ.

To make your life easier, ERPLAB does not require the events in the EventList text file to be listed in order of occurrence.  Thus, you can add any new events at the end of the file rather than inserting them at the appropriate place.  ERPLAB will use the onset time of each event to determine when it occurred.  The event number and the time difference are ignored when you import the text file.  ERPLAB will renumber the events after you have imported them.

<<Previous Section           Next Section >>


Back to Table of Contents