11.14: Exercise- Improving the Script and Adding 3D Channel Locations

Do You Need to Launch eStudio?

Before we get into making improvements to the script, I'm going to show you something that can save you a lot of time when you're testing a script. The first thing that MyScript4.m does when you run it is launch eStudio. But if eStudio is already running, do you really want to spend the time to launch it again? This can get very tiring. I know, because my original version of the script launched eStudio every time, even if it was already running, and it got very annoying after the 10th time or so. I therefore decided to show you a trick for seeing if it is already running.

Make sure that MyScript4.m is still open. Find the line near the beginning that launches eStudio with the estudio command, and replace that line with the following set of lines:

h = findobj('Tag', 'EStudio'); % Find the eStudio window (if it exists)
if isempty(h) % Check to see if the eStudio already exists
    disp('Launching eStudio');
    estudio;
else % Do the following steps if the eStudio window does not exist
    disp('eStudio is already running -- resetting EEG, ALLEEG, and CURRENTSET.');
    EEG = [];
    ALLEEG = [];
    CURRENTSET = 0;
    % You will still see the previous EEGsets in eStudio until you click the Refresh button in the EEGsets panel
end

The first of these lines (beginning h = findobj) takes advantage of the fact that, when eStudio launches, it creates a window with the tag EStudio. The findobj function in this line looks for a window with this tag, storing information about the window in the variable h. The next line uses the isempty function to see if h actually contains anything (i.e., if it is an empty variable). If it's empty, this implies that eStudio is not running, so the script launches it with the estudio command (after informing you with the disp command). Otherwise ("else"), it informs you that eStudio is already running and then resets the EEG, ALLEEG, and CURRENTSET variables. EEG and ALLEEG are set to empty arrays. CURRENTSET, which indicates which EEGset is currently selected, is set to zero. If we didn't reset EEG, ALLEEG, and CURRENTSET, the script would add onto any EEGsets that were already loaded, which is not what we want in this situation.

To test this, quit from eStudio and type clear all. Make sure you have saved your changes to MyScript4.m to disk, and then run the script. Because eStudio is not running, the first thing you should see is the message Launching eStudio, which indicates that h was empty (meaning that Matlab couldn't find the eStudio window) and the line disp('Launching eStudio'); was therefore executed. You will then see some text indicating that eStudio is launching. When eStudio finishes launching, the rest of the script will run and load all the EEGsets. If you click Refresh in the EEGsets panel, you'll be able to see the EEGsets.

Now go back to your script, select the first 16 lines (up through the end statement in the text you added to the script), and execute these lines (e.g., by control-clicking and telling the popup menu to evaluate the selection in the Command Window). You should see this message in the Command Window: eStudio is already running -- resetting EEG, ALLEEG, and CURRENTSET. And if you look at the EEG, ALLEEG, and CURRENTSET variables in Matlab's Workspace pane, you can see that they've been reset.

Now clear all the EEGsets from the EEGsets panel and run the whole script. It will print that same message again in the Command Window and then load all the EEGsets. As usual, you need to click Refresh in the EEGsets panel to see the EEGsets.

Using a Variable for the Equations Filename

Our next step will be to store the name of the file with the Channel Operations equations in a variable at the top of the script. This will make the script more robust.

Make sure that MyScript4.m is still open. After the set of lines that define the various folders and filenames, add this line:

Equations_filename = [DIR 'equations.txt'];

That line will create a variable that holds the path and filename of the file with the equations. It’s really easy to make an error when you create a variable like this. In fact, I initially made an error when I wrote that line of code. When you create a new variable for a path and filename, you should check it first before running your script. To do this, run that one line of code. (The DIR variable should already be set from when you ran the script earlier.) Then, type dir(Equations_filename) on the command line. The dir command lists any files that match the variable you specify inside the parentheses. When you run this command, you should get an error message saying that the file is not found.

Now type Equations_filename on the command line to see the value of this variable. Do you see the problem? We’re missing the slash between the path and the filename  (or a backslash on a Windows computer; see the text box below). Fix this by changing the code to:

Equations_filename = [DIR filesep '/equations.txt'];

filesep is a Matlab function that returns whatever file separator is appropriate for the operating system you are using (backslash for Windows, forward slash for Mac OS, UNIX, and Linux). You can see this by typing filesep in the Command Window. You’ll see that it returns ‘/’ if you’re running Mac OS, UNIX, or Linux, or ‘\’ if you’re running Windows.

Now run the new line of code for defining the Equations_filename variable, and then run the dir(Equations_filename) command. If Equations_filename is set correctly, the dir command should just print the name of the file (equations.txt).

Now replace the string holding the path and filename in the pop_eegchanoperator command with Equations_filename so that the command looks like this:

EEG = pop_eegchanoperator( EEG, Equations_filename , 'ErrorMsg', 'cw', 'KeepChLoc', 'on', 'Warning', 'on', 'Saveas', 'off'  );

Now run the updated script and click Refresh in the EEGsets panel. It should lead to the same result as the previous version of the script that didn’t use the Equations_filename variable, but the script is now more robust.

Now we're going to make a small improvement that will make your life easier someday. Here's the problem we want to prevent: when a script is running, you don’t usually want error and warning messages to appear as new windows that wait for you to respond. If you’re running a script overnight because it takes a long time, you don’t want the script to be waiting for a response to a warning message when you arrive the next morning. So, let’s change 'Warning', 'on' to 'Warning', 'off' so that warning messages aren’t printed. (But note that error messages will still be printed.) Go ahead and save the updated script.

Adding 3D Electrode Locations

Now you are going to see how to add 3D electrode location information to each channel. This information will be essential when you want to interpolate bad electrodes (because interpolation creates a new value at the bad electrode from a distance-weighted average of the other electrodes, and electrode locations are needed to get the distance information). It will also be essential if you want to plot scalp maps of your EEG or ERP data.

Select 1_N170 in the EEGsets panel, go to the EEGLAB Tools panel, and click the Chan locations button. This will launch a window like the one shown in Screenshot 11.8. The general idea is that EEGLAB has a file that contains a list of all the standard electrode names (from a modified version of the International 10/20 system) and the expected 3D location of each location on an average head. The routine will go through all of the electrode names in your EEGset, try to find the corresponding names in its file, and then add the 3D location information to the channel for each electrode name that it can find. If it can't find one or more of your electrode names, those channels won't get a 3D location.

The default file with the name-location pairs is standard_1005.elc, which you can see in the window shown in Screenshot 11.8. I prefer to use a different file, which is named standard-10-5-cap385.elp and is located in the Chapter_11 folder. To specify this file, click on the button with the three dots in it, and select standard-10-5-cap385.elp. Then click the Ok button, which will cause a very complicated new window to appear. This window allows you to adjust the locations. No adjustments are necessary, so just click the Ok button for this window. You'll then see the standard eStudio window for naming and saving the new EEGset that is being created. You can just accept the default name.

Now type eegh in the Command Window to see the history. The last few lines should contain the relevant line of code, which should look something like this (but with a different path to the file):

EEG=pop_chanedit(EEG, {'lookup','/Users/luck/Chapter_11/standard-10-5-cap385.elp'});

You can copy this line from the history into your script, right after the line that begins EEG = pop_eegchanoperator. However, this violates our rule about having information like paths and filenames in the middle of a script. In addition, because this line of code includes the path to the file, it will break if you ever move your experiment to a different location on your computer. To make it more robust, we want to use the DIR variable we created earlier that represents the current folder (even if you later shift everything to a new folder). To solve these problems,  add the following near the top of your script (under the line defining the Equations_filename variable):

ElectrodeLocation_file = [DIR filesep 'standard-10-5-cap385.elp'];

Then, change the pop_chanedit line to this:

EEG = pop_chanedit(EEG, {'lookup', ElectrodeLocation_file});

Now your script has defined the name of the file in a variable at the top, with the location being whatever your current folder is. If you move everything to a new folder, the script will still work as long as the folder holding the script and data is the current folder when you run the script.

Save your script, run it, and then click Refresh in the EEGsets panel. To see the channel locations, you can go to the Edit/Delete Channels & Locations panel and click Add or edit chan locations. You should see a new window with an image of the electrode locations superimposed on a head, with the location information in a table on the right side of the window. Once you've verified that everything looks okay, you can close this window.

Naming and Saving the EEGset

Our next step will be to update the name of the EEGset that we've modified to indicate that it has been referenced and that channel locations have been added. Then we'll save the EEGset to disk.

First, type EEG.setname in the Command Window so that you can see the name of the current EEGset. If Subject 10 is the active EEGset, you should see that the setname is '10_N170'. To update the setname, add the following line to your script after the line with the pop_chanedit command:

EEG.setname = [EEG.setname '_ref_chanlocs'];

This takes the current setname and appends _ref_chanlocs to the end, storing the result in the EEG.setname variable. That was pretty easy. Note that you should have added this line right before the line with the eeg_store command, so the new setname will be stored in ALLEEG and therefore appear in the EEGsets panel once you click the Refresh button. This line of code violates my rule about using variables to define values, because I didn’t define a variable for '_ref_chanlocs'. Later, in the script named Script4b.m, you'll see that I have fixed this problem by using a variable named Setname_suffix.

Now let’s add some code for saving the updated EEGset to your hard drive, in the same folder as the original EEGset. You should first use the GUI to save the current EEGset on your hard drive so that you can use the history to see the command for saving an EEGset file. To do this, go to the EEGsets panel, click the Save a Copy button, and use the suggested name for the EEGset and filename (10_N170_ref_copy). Now type eegh to see the history. You should see something like this:

EEG = pop_saveset( EEG, 'filename','10_N170_ref_copy.set','filepath','/Users/luck/Chapter_11');

Copy that line from the Command Window and paste it into your script after the line with the eeg_store command. But we want to make some changes before we use it. First, we don’t want the file to be named 10_N170_ref_copy.set. I like to have the filename be the same as the setname, but with .set at the end. To accomplish this, change the new line of code by replacing 'tmp.set' with [EEG.setname '.set'] (which creates a string with the setname followed by .set).

We also want to change the path so that it uses the Subject_DIR variable we previously created to hold the path for this subject’s data. To do this, change the string that currently lists the path (which is '/Users/luck/Chapter_11' on my computer but will be something else on your computer) to Subject_DIR. This line of code should now look like this:

EEG = pop_saveset( EEG, 'filename', [EEG.setname '.set'], 'filepath', Subject_DIR);

Before you run the code, I want to show you one more little trick for dealing with bugs and other kinds of errors. I probably made an error at least 50% of the time when I added code to one of the scripts for this book. If you have a script that loops through the data from 40 participants, it can be really annoying to have the script show an error message 40 times before it finishes. You can usually type ctrl-C to stop the code after the first error, but that doesn’t always work. So, the first time I try out a new script, I just try it with the data from the first participant. I do that by following the line that defines the subject IDs with another line that lists only the first subject ID. For example, near the top of MyScript4.m, I have these two lines:

SUB = [ 1 2 3 5 6 7 8 9 10 ]; %Array of subject numbers

%SUB = [ 1  ]; %Just the first subject

The first time I run the script after making a change, I simply remove the % symbol on the second of the two lines. This overwrites the original contents of SUB and replaces it with only the ID for Subject 1, and the loop runs only for this one subject. Once I get the script to work for that one subject, I then put the  % symbol back and run the script again.

To see this in action, add the line with SUB = [ 1  ]; (without the % symbol) right after the line that currently defines the SUB variable. Now try running your updated version of MyScript4.m. If you get an error, you can fix it and try again.

Once you get it to run, you will notice that nothing seems to have changed in the EEGsets panel. That's because eStudio doesn't know that you've updated the contents of ALLEEG. To get eStudio synced with the current contents of ALLEEG, you need to click Refresh in the EEGsets panel. Then you should see an EEGset only for Subject 1, and it should be named 1_N170_ref_chanlocs.

Now that the script is working with Subject 1, you can comment out the SUB = [ 1  ]; line (i.e., add the % symbol at the beginning of the line) and run the script again to process all the subjects. Once the script finishes, you'll need to click Refresh in the EEGsets panel to see the EEGsets for all the subjects.

Now you have a robust, well-designed script that launches eStudio if necessary, loads the EEGsets, references the data, adds the 3D channel locations, and saves the updated EEGsets to your hard drive. You can now open Script4b.m to see my version of this script. It has comments that explain each line of code.

Script4b.m also uses a slightly different version of the equations file, named Reference_Equations.txt, which reorders the channels in addition to referencing them. The order of the channels in the original data files reflects the order of electrodes in the BioSemi recording system we used to collect the data. This ordering is convenient for the process of placing the electrodes on the head, but not for viewing the data. I reordered the channels so that they are in sets that go from left to right for a given line of electrodes (e.g., F7, F3, Fz, F4, F8 for the Frontal channels).