Example 3: A Simple Script That Actually Does Something Useful

Note: A complete version of this script is available in Test_Data > Script_Examples > Script3.m.  However, this script may not work on your computer, because it assumes that the Test_Data folder is in a specific location.  See instructions below for details.

Now we're ready to make a slightly more complicated script that actually does something useful: It does all the processing steps between loading an EEG and making an average for a single subject.  Why is this useful?  Imagine that you've spent 30 minutes processing a subject's data with the EEGLAB GUI, and then you decide you want to change something at an early stage of the processing sequence.  Repeating all the subsequent steps can be boring and time-consuming, and using a script can save you time and aggravation.  In addition, the script then becomes a record of exactly how the data were processed, which can be useful 3 years later when you finally write a paper.  An even bigger benefit comes with slightly more complex scripts that can loop through all of your subjects.  And once you master that, you will be ready to write scripts that process the data in completely new ways that would not be possible from the GUI.

In this example, we will use the GUI to do several processing steps on an EEG dataset for one subject, look at the history, and then use the history to create a simple script that can be used to repeat these steps on another subject.  The processing steps will be the first few steps from the ERPLAB Tutorial.  Specifically, we'll load an EEG dataset (S1_EEG.set), add channel location information, add a simple EVENTLIST structure, run BINLISTER to assign events to bins, epoch the data, perform artifact detection, and average the epochs to create an ERPset.  Here we will provide an abbreviated description of how to accomplish each step in the GUI; see the ERPLAB Tutorial for a more detailed explanation.

Getting Started

To begin, launch Matlab and eeglab; if they have already been launched, quit from eeglab, type clear all, and launch eeglab again.  This will make sure that you are "starting from scratch" and won't get confused by old things in the history.  Now set Matlab's current directory to be the folder with the tutorial data from subject S1.  To do this, look at the top of the Matlab command window, where you will see a drop-down menu displaying the current directory (see screenshot below).  Click on the browse button (labeled with '…') to the right of the current directly and choose the S1 folder.  The top of the window will then look something like this (although the details depend on what operating system you are using and where you've put the tutorial data):

Doing the processing steps with the GUI to create a history

Now we will do several processing steps in the GUI so that we can create a history that will be the basis of the script. 

Step 1: Load the original EEG dataset. Our first step is to load the original EEG file using FILE > Load existing dataset to load the file named S1_EEG.set.  After you do this, typing eegh will show you the script command for this step:

>> eegh

[ALLEEG EEG CURRENTSET ALLCOM] = eeglab;

EEG = pop_loadset('filename','S1_EEG.set','filepath','/Users/luck/Documents/Software_Development/ERPLAB_Toolbox/documentation/Scripting/Examples/S1/');

Step 2: Adding channel locations. Our next step is to add location coordinates for each electrode site.  Select Edit > Channel locations, which will bring up the window shown here:

Click Ok, and you will see the window shown here:

Accept all of the default values and simply click Ok.  This will add the coordinates to the current dataset.

Next, you should change the name of the dataset to S1_Chan so that you can differentiate between this version and the original version.  To do this, select Edit > Dataset info.  This will bring up the window shown below, and you should enter S1_Chan in the Dataset name field.  Click Ok, and then look in the Datasets menu.  You should now see that it is named S1_Chan.

You can now save the modified dataset by selecting File > Save current dataset as, naming the file S1_Chan.set.

Now if you type eegh, you will see several additional commands have been added, corresponding to adding the electrode locations, changing the name of the dataset, and saving it as a file:

>> eegh

[ALLEEG EEG CURRENTSET ALLCOM] = eeglab;

EEG = pop_loadset('filename','S1_EEG.set','filepath','/Users/luck/Documents/Software_Development/ERPLAB_Toolbox/documentation/Scripting/Examples/S1/');

[ALLEEG, EEG, CURRENTSET] = eeg_store( ALLEEG, EEG, 0 );

EEG=pop_chanedit(EEG, 'lookup','/Users/luck/Documents/Software_Development/eeglab9_0_2_3b/plugins/dipfit2.2/standard_BESA/standard-10-5-cap385.elp');

[ALLEEG EEG] = eeg_store(ALLEEG, EEG, CURRENTSET);

EEG = eeg_checkset( EEG );

EEG = pop_editset(EEG, 'setname', 'S1_Chan');

[ALLEEG EEG] = eeg_store(ALLEEG, EEG, CURRENTSET);

EEG = eeg_checkset( EEG );

EEG = pop_saveset( EEG, 'filename','S1_Chan.set','filepath','/Users/luck/');

[ALLEEG EEG] = eeg_store(ALLEEG, EEG, CURRENTSET);

Step 3: Creating the EVENTLIST structure. Next you will add an EVENTLIST structure to the EEG structure.  We will do a very simple version of this here (without adding text labels for the events).  To do this, select ERPLAB > EventList > Create EEG EventList – Basic, and just run it with the default parameters as shown in the screenshot below:

This will create a new dataset, and ERPLAB will suggest that you name it S1_Chan_elist.  Go ahead and use this name.  You do not need to save it as a file.  You will be able to see this new dataset in the Datasets menu.

Step 4: Assigning events to bins with BINLISTER. The next step is to use BINLISTER to figure out which events belong in which bins.  In the parent directory, you should find a bin descriptor file named binlist_demo_1.txt.  If you can't find it, you can create it with the following contents:

bin 1

Frequent followed by correct response

.{11;122;22;111}{9}

bin 2

Rare followed by correct response

.{21;112;12;121}{9}

Run BINLISTER by selecting ERPLAB > Assign Bins (BINLSTER).  Tell BINLISTER to load the bin descriptor file from binlist_demo_1.txt (or the file you created) and then run it with the default parameters, as shown in the following screen shot:

When it is done, BINLISTER will suggest S1_Chan_elist_nelist as the name of the dataset, and you should use this name.

Step 5: Epoching the data. The next step is to extract epochs based on the bins created in the previous step.  To do this, select ERPLAB > Extract Bin-based Epochs and enter the parameters shown in the screen shot:

The epoching routine will suggest S1_Chan_elist_nelist_be as the name of the dataset, and you should use this name.

Step 6: Artifact Detection. The next step is to detect artifacts with ERPLAB > Artifact Detection > Moving window peak-to-peak threshold with the parameters shown in the screen shot:

It should reject 28.8% of the trials (as indicated in the command window).  Accept the results and use the recommended name of S1_Chan_elist_nelist_be_ar for the dataset.

Step 6: Averaging. We are now ready to average the data with ERPLAB > Compute averaged ERP with the default parameters (which should look something like the following screenshot):

Use S1_ERP as the name of the ERPset and save it in a file named S1_ERP.erp, as shown here:

You can see the whole series of commands prior to creating the average by typing eegh in the command window, which should produce something like this:

>> eegh

[ALLEEG EEG CURRENTSET ALLCOM] = eeglab;

EEG = pop_loadset('filename','S1_EEG.set','filepath','/Users/luck/Documents/Software_Development/ERPLAB_Toolbox/Test_Data/S1/');

[ALLEEG, EEG, CURRENTSET] = eeg_store( ALLEEG, EEG, 0 );

EEG=pop_chanedit(EEG, 'lookup','/Users/luck/Documents/Software_Development/eeglab9_0_2_3b/plugins/dipfit2.2/standard_BESA/standard-10-5-cap385.elp');

[ALLEEG EEG] = eeg_store(ALLEEG, EEG, CURRENTSET);

EEG = eeg_checkset( EEG );

EEG = pop_editset(EEG, 'setname', 'S1_Chan');

[ALLEEG EEG] = eeg_store(ALLEEG, EEG, CURRENTSET);

EEG = eeg_checkset( EEG );

EEG = pop_saveset( EEG, 'filename','S1_Chan.set','filepath','/Users/luck/Documents/Software_Development/ERPLAB_Toolbox/Test_Data/S1/');

[ALLEEG EEG] = eeg_store(ALLEEG, EEG, CURRENTSET);

EEG = pop_creabasiceventlist(EEG, '', {'boundary'}, {-99}, 1);

[ALLEEG EEG CURRENTSET] = pop_newset(ALLEEG, EEG, 1,'gui','off');

EEG = pop_binlister( EEG, '/Users/luck/Documents/Software_Development/ERPLAB_Toolbox/Test_Data/S1/binlister_demo_1.txt', 'no', '', 0, [], [], 0, 0, 0);

[ALLEEG EEG] = eeg_store(ALLEEG, EEG, CURRENTSET);

EEG = pop_epochbin( EEG , [-200.0  800.0],  'pre');

[ALLEEG EEG CURRENTSET] = pop_newset(ALLEEG, EEG, 3,'gui','off');

EEG = pop_artmwppth( EEG, [-200  798], 100, 200, 50,  1:16,  1);

[ALLEEG EEG CURRENTSET] = pop_newset(ALLEEG, EEG, 4,'gui','off');

This does not include the command for computing the averaged ERP, because the result of that command is an ERP structure, not a new EEG structure.  Any commands that operate on the ERP structure can be seen with the erph command.  If you type erph in the command window, you will see something like this:

>> erph

ERP = pop_averager( ALLEEG,4, 1, 1 );

ERP = pop_savemyerp(ERP, 'erpname', 'S1_ERP', 'filename', '/Users/luck/Documents/Software_Development/ERPLAB_Toolbox/Test_Data/S1/S1_ERP.erp', 'gui', 'erplab');

Using the history to make a script

We are now (finally!) ready to turn this history into a script.  You can simply copy the output of the eegh and erph commands into a new script file.  You can leave out the first line of the EEGLAB history (the line that launches EEGLAB).  You can also leave out the line that says EEG = eeg_checkset(EEG), which is just some EEGLAB housekeeping that you can usually ignore.  And you can add eeglab redraw at the end.  The whole script should look something like this, but with a different path to the S1 folder, reflecting the fact that the files are not stored in exactly the same place on your computer that they are stored in my computer.  In addition, the file standard-10-5-cap385.elp, which is used for determining electrode locations, will probably be in a different place in your file system (but your history should give the correct location).

EEG = pop_loadset('filename','S1_EEG.set','filepath','/Users/luck/Documents/Software_Development/ERPLAB_Toolbox/Test_Data/S1/');

[ALLEEG, EEG, CURRENTSET] = eeg_store( ALLEEG, EEG, 0 );

EEG=pop_chanedit(EEG, 'lookup','/Users/luck/Documents/Software_Development/eeglab9_0_2_3b/plugins/dipfit2.2/standard_BESA/standard-10-5-cap385.elp');

[ALLEEG EEG] = eeg_store(ALLEEG, EEG, CURRENTSET);

EEG = pop_editset(EEG, 'setname', 'S1_Chan');

[ALLEEG EEG] = eeg_store(ALLEEG, EEG, CURRENTSET);

EEG = pop_saveset( EEG, 'filename','S1_Chan.set','filepath','/Users/luck/Documents/Software_Development/ERPLAB_Toolbox/Test_Data/S1/');

[ALLEEG EEG] = eeg_store(ALLEEG, EEG, CURRENTSET);

EEG = pop_creabasiceventlist(EEG, '', {'boundary'}, {-99}, 1);

[ALLEEG EEG CURRENTSET] = pop_newset(ALLEEG, EEG, 1,'gui','off');

EEG = pop_binlister( EEG, '/Users/luck/Documents/Software_Development/ERPLAB_Toolbox/Test_Data/S1/binlister_demo_1.txt', 'no', '', 0, [], [], 0, 0, 0);

[ALLEEG EEG] = eeg_store(ALLEEG, EEG, CURRENTSET);

EEG = pop_epochbin( EEG , [-200.0  800.0],  'pre');

[ALLEEG EEG CURRENTSET] = pop_newset(ALLEEG, EEG, 3,'gui','off');

EEG = pop_artmwppth( EEG, [-200  798], 100, 200, 50,  1:16,  1);

[ALLEEG EEG CURRENTSET] = pop_newset(ALLEEG, EEG, 4,'gui','off');

ERP = pop_averager( ALLEEG,4, 1, 1 );

ERP = pop_savemyerp(ERP, 'erpname', 'S1_ERP', 'filename', '/Users/luck/Documents/Software_Development/ERPLAB_Toolbox/Test_Data/S1/S1_ERP.erp', 'gui', 'erplab');

eeglab redraw;

Before running this script, close EEGLAB, type clear all in the Matlab command window, and restart EEGLAB.   This way we can avoid being confused by the datasets that you created in the EEGLAB GUI.  Now go ahead and run your new script.  You should see lots of information being printed in the command window as the various commands run.  At the end, when the pop_averager() command has finished averaging, it will put up a window asking you to name and save the averaged ERP.  It should have the correct name (S1_ERP) already, and you can go ahead and save it.  It might ask you if you want to overwrite an existing file (that you created previously), and you can go ahead and do that.

If your script generates error messages, you should make sure that it is exactly like the script shown above, except with path information that matches the location of the S1 folder on your computer.

Once the script is done running, you will be able to see the S1_ERP ERPset in the ERPsets menu and four different datasets in the Datasets menu (assuming that you included eeglab redraw in your script; if not, type it in the command window now).

Ordinarily, you will not want your scripts to put up windows that require your intervention; you'll want your scripts to run completely automatically.  You can eliminate the window for naming and saving the ERP by eliminating the 'gui', 'erplab' portion of the pop_averager() command.  However, if you do this, you won't be able to see the newly created ERP structure in the ERPsets menu (ERPLAB doesn't yet have an equivalent of eeglab redraw).  However, you can simply load the ERP into ERPLAB after the script is complete with ERPLAB > Load existing ERPset.