Chapter 01: Loading Data in EEGLAB
EEGLAB graphic interface is built on top of the powerful Matlab scripting language. Enjoying the full capabilities of EEGLAB for building macro commands and performing custom and automated processing requires the ability to manipulate EEGLAB data structures in Matlab. After opening the Matlab desktop, we recommend running the following demos and reading the following help sections.
In the Help Content, select menu item Help Demos and run the following demos:
- Mathematics - Basic Matrix Operations
- Mathematics - Matrix Manipulations
- Graphics - 2-D Plots
- Programming - Manipulating Multidimensional Arrays
- Programming - Structures
In the Help Content, read and practice at least the following sections:
- Getting Started - Matrices and Arrays - Matrices and Magic Squares
- Getting Started - Matrices and Arrays - Expressions
- Getting Started - Matrices and Arrays - Working with Matrices
- Getting Started - Graphics - Basic Plotting Functions
- Getting Started - Programming - Flow Control
- Getting Started - Programming - Other Data Structures
- Getting Started - Programming - Scripts and Functions
Each section or demo (if read thoroughly) should take you about 10 minutes, for a total here of about 2 hours. We encourage you to watch these demos and read these sections over several sessions.
If you do not have access to the Matlab demos, here is a short, online introduction to Matlab (recommended pages, 1 to 12).
If you are an experienced Matlab programmer, you may want to read through the EEGLAB tutorial appendices on the EEG dataset and STUDY studyset structures and their sub-structures, and on EEGLAB script writing.
Installing EEGLAB and tutorial files
When you uncompress EEGLAB you will obtain a folder named "eeglabxxxx" (note: current version number varies). Under Windows, Matlab usually recommends, although this is not required, that you place toolboxes in the Application/MatlabR14/toolbox/ folder (note: name varies with the Matlab version). In Linux, the Matlab toolbox folder is typically located at /usr/local/pkgs/Matlab-r14sp2/toolbox/. You may also place the folder anywhere else on your path.
Start Matlab and list the eeglab folder in the Matlab search path. If you started Matlab with its graphical interface, go to menu item file and select set path, which opens the following window.
Or, if you are running Matlab from the command line, type in "pathtool", which will also call up this window. Click on the button marked Add folder and select the folder "eeglabxxxxx", then hit OK (EEGLAB will take care of adding its subfolder itself). Hit save in the pathtool window, which will make eeglab available for future Matlab sessions. Note that if you are installing a more recent version of EEGLAB, it is best to remove the old version from the Matlab path (select and hit Remove) to avoid the possibility of calling up outdated routines.
Starting Matlab and EEGLAB
Here we will start Matlab and EEGLAB. Note that paragraphs that begin with KEY STEP are necessary to what follows in the tutorial. Paragraphs that begin with Exploratory Step are written to help you explore various EEGLAB features.
KEY STEP 1: Start Matlab.
WINDOWS: Go to Start, find Matlab and run it.
Mac Option 1: Start from the Matlab icon in the dock or in the application folder.
Mac Option 2: Start X11 and in a terminal window type "matlab" and hit enter. For added stability type "matlab -nodesktop" to run it without its java desktop.
Linux: Open a terminal window and follow the Mac Option 2 instructions above.
KEY STEP 2 (optional): Switch to the data directory (folder).
In this case the directory you switch to should be the directory containing the example data provided for this tutorial. If you are running Matlab with its java desktop, you may also browse for the directory by clicking on the button marked "…" in the upper right of the screen,
which opens the window below. Double-click on a directory to enter it. Double-clicking on ".." in the folder list takes you up one level. Hit OK once you find the folder or directory you wish to be in. Alternatively, from the command line use "cd" (change directory) to get to the desired directory.
KEY STEP 3: Start EEGLAB.
Just type "eeglab" at the Matlab command line and hit enter.
The blue main EEGLAB window below should pop up, with its seven menu headings: File, Edit, Tools, Plot, Study, Datasets, Help arranged in typical (left-to-right) order of use.
Opening an existing dataset
KEY STEP 4: Load the sample EEGLAB dataset.
Select menu item File and press sub-menu item Load existing dataset.
In the rest of the tutorial, we will use the convention: Menu_item > Submenu_item to refer to selecting a menu choice (e.g., here select File > Load existing dataset).
Under Unix, the following window will pop up (the aspect of the window may be different under Windows):
To learn how to create EEGLAB datasets from your own data, see the tutorial on Importing data and data events.
Select the tutorial file "eeglab_data.set" which is distributed with the toolbox (available here - press the right mouse button and select save link as if strange characters appear -' or in the "sample_data" sub-directory if you downloaded the full version of EEGLAB) and press Open.When the dataset is loaded by EEGLAB, the main EEGLAB window shows relevant information about it -- the number of channels, sampling rate, etc...
Editing event values
The fields type, position, and latency have different values for each of the 154 events in the dataset.
Exploratory Step: Editing Event Values.
Select menu Edit > Event Values to call up a window where we can read and edit these values:
Scroll through the events by pressing the >, >>, <, and << keys above.
We will now briefly describe the experiment that produced the sample dataset to motivate the analysis steps we demonstrate in the rest of the tutorial.
Sample experiment description
In this experiment, there were two types of events "square" and "rt"; "square" events correspond to the appearance of a green colored square in the display and "rt" to the reaction time of the subject. The square could be presented at five locations on the screen distributed along the horizontal axis. Here we only considered presentation on the left, i.e. position 1 and 2 as indicated by the position field (at about 3 degree and 1.5 degree of visual angle respectively). In this experiment, the subject covertly attended to the selected location on the computer screen responded with a quick thumb button press only when a square was presented at this location. They were to ignore circles presented either at the attended location or at an unattended location. To reduce the amount of data required to download and process, this dataset contains only targets (i.e., "square") stimuli presented at the two left-visual-field attended locations for a single subject. For more details about the experiment see Makeig, et al., Science, 2002, 295:690-694.
When using events in an EEGLAB dataset, there are two required event fields: type and latency, plus any number of additional user-defined information fields. It is important to understand here that the names of the fields were defined by the user creating the dataset, and that it is possible to create, save, and load as many event fields as desired.
Note also that type and latency (lowercase) are two keywords explicitly recognized by EEGLAB and that these fields must be defined by the user unless importing epoch event information (Note: If only field latency is defined, then EEGLAB will create field type with a constant default value of 1 for each event). Unless these two fields are defined, EEGLAB will not be able to handle events appropriately to extract epochs, plot reaction times, etc. The Importing data tutorial explains how to import event information and define fields.
About this dataset
Here we describe how to edit and view the text field which describes the current dataset, and is stored as a part of that dataset.
Exploratory Step: Editing the Dataset Description.
Select Edit > About this dataset. A text-editing window pops up which allows the user to edit a description of the current dataset. For the sample data, we entered the following description of the task. Press SAVE when done.
Scrolling through the data
Here we learn how to visualize data and reject portion of continuous data.
Exploratory Step: Scrolling data.
To scroll through the data of the current dataset, select Plot > Channel data (scroll). This pops up the eegplot() scrolling data window below. Note that the sample data file contains "faked" continuous EEG data. To reduce (your) download time, this "pseudo-continuous" EEG dataset was actually constructed by concatenating eighty separate three-second data epochs (which we will later separate again).
To the right of the plot window is the vertical scale value (unit, i.e. microvolts), which indicates the "height" of the given vertical scale bar. In this case, that value is 80 (microvolts). The same value is also shown in the lower right-hand edit box, where we can change it as explained below.
Exploratory Step: Voltage Scale.
Change the "Scale" edit-text box value to about 50, either by repeatedly clicking on the "-" button or by editing the text value from the keyboard, and press the Enter key to update the scrolling window.
Exploratory Step: Adjusting time range.
To adjust the time range shown (horizontal scale), select eegplot() menu item Settings > Time range to display, and set the desired window length to "10" seconds as shown below,
then press OK to display the changes.
Exploratory Step: Number of Channels to Display.
To adjust the number of channels displayed, select eegplot() menu item Settings > Number of channels to display and enter the desired number of channels to display in the screen (for instance "16").
This will return a scrolling eegplot() window with a vertical channel-set slider on the left of the plot. Use it to scroll vertically through all the channels.
Exploratory Step: Zoom.
To zoom in on a particular area of a data window, select eegplot() menu item Settings > Zoom off/on > Zoom on. Now using your mouse, drag a rectangle around an area of the data to zoom in on. The scrolling window may now look similar to the following. Click the right button on the mouse to zoom out again. Use menu Setting > Zoom off/on > Zoom off to turn off the zoom option.
Exploratory Step: Grid Lines.
To display horizontal (x) and vertical (y) grid lines on the data, select Display > Grid > X grid on or Display > Grid > Y grid on. Repeat this process to turn off either set of grid lines.
The eegplot() window also allows you to reject (erase) arbitrary portions of the continuous data. The function eegplot() can be called from both menu items Plot > Scroll data and Tools > Reject continuous data using the REJECT button on the bottom right corner.
Exploratory Step: Rejecting Data.
Close the current eegplot() window and call Tools > Reject Continuous Data by eye from the main EEGLAB window. A warning message appears, click on continue. To erase a selected portion of the data, first drag the mouse along the area of interest to mark it for rejection. It is possible to mark multiple regions. To undo a rejection mark, click once on the marked region.
(Note: Zooming must be disabled to select a portion of the data.)
Now, to erase the marked data regions, click the (lower right) REJECT button (above). A new dataset will be created with the marked regions removed. (Note: EEGLAB will also add new "rejection boundary" events to the new dataset event list. These insure that subsequent epoch selections will not cross non-contiguous rejection boundaries). For more details about rejecting continuous data regions and data epochs, see the data rejection tutorial.
Click OK (below) to create the new dataset with the marked data portions removed.
Press OK to create the new dataset. The EEGLAB main window now looks like:
Since we only performed this rejection for illustrative purposes, switch back to the original dataset by selecting main window menu item Datasets > Dataset 1 eeglab_data.
Exploratory Step: Deleting a Dataset from Memory.
To delete the newly created second dataset, select File > Clear dataset(s) or Edit > Delete dataset(s) and enter the dataset index, "2" as shown below, and press OK.
The second dataset will now be removed from the Matlab workspace. (Note: It is not necessary to switch back to the first dataset before deleting the second. It is also possible to delete several datasets at once from this window by entering their indices separated by spaces.)