11.13: Exercise- Referencing with a Script

In this exercise, we’ll add referencing to the script from the previous exercise so that the new script is more useful. You’ll also learn some important strategies along the way.

As you may recall, the ERP CORE data were recorded without a reference (which is possible in only a few recording systems), so we need to use EEG Channel Operations to reference the data. We’ll also add bipolar VEOG and HEOG channels. The N170 is traditionally referenced to the average of all sites (see Chapter 5), and that’s what we’ll do in this example.

You should already have 9 datasets loaded from the previous exercise. If you don’t, run Script4.m again. With the 10_N170 dataset active, select EEGLAB > ERPLAB > EEG Channel operations. Clear out any equations that are already set, set the Mode to Create new dataset, and make sure the box labeled Try to preserve channel locations is checked. Click the Reference Assistant button, and enter the parameters shown in Screenshot 11.5.

Screenshot 11.5

The key parameter is avgchan(1:33), which tells it to use the average of all 33 channels as the reference. Then click OK, which should fill the equations window with an equation for referencing each of the 33 channels to the average of Channels 1–33. Then add these two equations to create bipolar HEOG and VEOG channels:

nch34 = ch31 - ch32 Label HEOG-bipolar

nch35 = ch33 - ch16 Label VEOG-bipolar

Then click Run to execute the routine. Now type eegh to see the script command for EEG Channel Operations, which begins with EEG = pop_eegchanoperator. This command is extremely long, because it contains all 35 equations in it. There’s a better way to do this: Instead of having this huge command, we can put all the equations in a file and pass the filename instead of the list of equations.

Seeing a List of the Channels in a Dataset or ERPset

When you’re using the EEGLAB/ERPLAB GUI, it’s usually pretty easy to see what channels are in a dataset or ERPset. However, this information isn’t so obvious when you’re writing scripts. Here’s a little trick that I use quite often: If you double-click on the name of a variable in the Workspace pain of the main Matlab window, a Variables pane will appear and show the contents of that variable. For example, you can double-click on the EEG variable to see its contents. EEG is a complex structure with many fields, and you can double-click on the name of a field to see the contents of that field. The screenshot below shows what I see when I first double-click on the EEG variable and then double-click on the chanlocs (channel locations) field. This also works for ERPsets if you double-click on the ERP variable.

To see how this works, select the original version of 10_N170 from the Datasets menu and launch EEG Channel operations again. You should still have the 35 equations from before. Near the bottom of the window, click the Save list as button to save the list of equations as a file. Name the file equations.txt. In addition to saving the file, this command puts the filename (including the entire path) in the File: text box. Now, select the check box labeled Send file rather than individual equations, and click Run to execute the routine. Now when you type eegh on the command line, you should see a much shorter line of code that looks something like this:

EEG = pop_eegchanoperator( EEG, '/Users/luck/Ch_10_Scripting/Exercises/equations.txt' , 'ErrorMsg', 'popup', 'KeepChLoc', 'on', 'Warning', 'on' );

Let’s take a closer look at this command. We send the EEG variable as the first parameter. The routine then sends back a new version of this variable as its output. The second parameter is the filename for the equations file (including the whole path, which will be different on your computer). Then we have a sequence of pairs of parameters, which occur in the order parameter name, parameter value. For example, the sequence of parameters 'ErrorMsg', 'popup' tells the routine to set the error message option to a value of popup, which means that error messages will be delivered in popup windows. The next pair of parameters is 'KeepChLoc', 'on', which tells the routine that the option for keeping the channel locations should be on (which you had set from the GUI by checking the box the option labeled Try to preserve channel locations). The use of pairs of parameters—one for the name of the parameter and one for the value—makes it easier to understand what the parameters are doing. This approach is common in Matlab scripts and functions, and it’s used extensively in EEGLAB and ERPLAB routines.

How do you know what options are available for a command like pop_eegchanoperator? You can use Matlab’s help feature. There are several ways to access this feature. One common way is to type help pop_eegchanoperator on the command line. Another way is to select the name of the routine in the Command Window (or in a script) and then right-click or control-click on it to get a contextual menu, which contains a Help on Selection item. Try one of these methods to see the help for pop_eegchanoperator. When you do this, Matlab simply shows you all of the comments (lines of text beginning with the % character) at the top of the .m file containing the command (e.g., the pop_eegchanoperator.m file, which contains the code for this routine and is located in a subfolder deep inside the EEGLAB folder that was created when you installed EEGLAB and ERPLAB). This works with any command, including built-in Matlab commands like pwd and EEGLAB and ERPLAB commands like pop_eegchanoperator.

Now it’s time for an embarrassing admission: When I looked up the help for pop_eegchanoperator, I found that it didn’t actually list the optional parameters. In fact, it wasn’t very helpful at all. This is one of the first routines that we wrote for ERPLAB, and I’m guessing that we hadn’t yet established a good workflow that included careful documentation of all the features of each routine. This has now been fixed. And here’s another embarrassing admission: I’ve seen lots of shortcomings in the ERPLAB help information as I’ve worked on this book. I don’t have a good excuse for this. I can tell you that most programmers hate writing documentation—once the code is done, it’s not much fun to write the documentation. But that’s not a good excuse. I’m going to add “go through all the ERPLAB help” to my list of things to do after I finish this book.

But let’s turn lemons into lemonade and use this as an opportunity to learn how to overcome unclear or missing documentation.

Lemonade

There’s an old saying that “When life gives you lemons, make lemonade.” I prefer the snarkier version, “When life gives you lemons, squeeze them into the open wounds of your enemies.”

When I ran into this problem with pop_eegchanoperator, I simply opened the pop_eegchanoperator.m file and looked at the code. I didn’t have to go searching through my file system for this file. I just found pop_eegchanoperator in the Command Window, selected it, control-clicked on it to get a contextual menu, and selected Open Selection. Give that a try to open the pop_eegchanoperator.m file.

If you’re not an expert in Matlab scripting, you may wonder how you’re going to understand the code in the pop_eegchanoperator.m file? You’re interested in finding out about the options, and you know that one of the options is ErrorMsg, so it would make sense to do a search for that string in the file. If you do this, you’ll eventually find this line:

p.addParamValue('ErrorMsg', 'cw', @ischar); % cw = command window

From this line you can infer that a possible value for this parameter is 'cw', and that this will send the error messages to the Command Window. If you search some more, you’ll find this set of lines:

if strcmpi(p.Results.ErrorMsg,'popup')

        errormsgtype = 1; % open popup window

From these two lines, you can see that the 'popup' value opens a popup window. So, now you’ve learned a strategy for figuring out how a routine works and what the options are (and I’ve learned that I need to put more effort into making sure that the ERPLAB help information is complete).

Now that you’ve learned about the command for EEG Channel Operations, let’s add it to the script we started in the previous exercise. Open Script4.m (if it’s not already open), and save it as MyScript4.m. Copy the pop_eegchanoperator line from eegh history in the Command Window to the clipboard and then paste it into MyScript4.m right after the line that begins with EEG = pop_loadset. Make sure you’ve pasted the version that uses the equations.txt file. Then save the updated MyScript4.m file. (I always save a script before running it—if there’s an error that crashes Matlab, I don’t want to lose the new code that I just added.)

Now quit EEGLAB, type clear all, and run MyScript4.m to see it work. You should see EEGLAB launch and then lots of text appear in the Command Window (mainly from EEG Channel Operations), including a line that says something like Processing Subject 9 of 9, ID = 10 as each individual subject is being processed. Once the script finishes, you should plot the EEG from one of the datasets, and then you’ll see that you now have bipolar VEOG and HEOG channels.

If you run into an error, make sure that you followed the above instructions carefully, and think about the logic of what you’re doing. You can also consult the Troubleshooting Tips in Appendix 2. The next several sections of this chapter will require you to make various additions to MyScript4.m, and you’ll almost certainly make at least one error at some point. When you do, feel free to make a few unkind comments about my parentage, and then remember that errors are a big part of scripting and that one of the goals of this book is for you to learn how to find and fix problems. Appendix 2 ends with some recommendations for writing code in a way that reduces the likelihood of errors.

After you get the script to run correctly, I want you to spend a moment thinking about how easy it was to add the step for referencing the data to the prior script. Once you had the basic script for looping through the participants and opening their datasets, you just had to run EEG Channel Operations from the GUI, get the history, and copy the command from the history to the appropriate point in the script. Done!

Well, not so fast. You’ll usually want to make a few changes to the command that you copied from the history. For example, the new line of code you added to the script broke my rule about values (such as filenames) being defined as variables at the top of the script. If you moved this script and the equations.txt file to a new folder, the script would break. The next exercise will solve this problem and make some additional improvements.