11.14: Exercise- Improving the Referencing Script

In this exercise, we’re going to make some improvements to the script from the previous exercise, including defining a variable for the name of the equations file and saving the dataset to your hard drive.

Make sure that MyScript4.m is still open. At the end of the set of lines that define the other 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 '/equations.txt'];

Now run that line of code and then 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', 'popup', 'KeepChLoc', 'on', 'Warning', 'on' );

Quit EEGLAB, type clear all, and then save and run the updated script. 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.

Forward Slashes and Backslashes

Windows uses a backslash (\) to separate the elements of a path, whereas Mac OS, UNIX, and Linux use a forward slash (/). Matlab is smart enough to convert to the appropriate separator for your computer. I don’t really trust it, though, so I like to use a more explicit approach using a Matlab function named filesep. This function returns the appropriate file separator for the computer that the script is running on. For example, I would define the variable for the equations file as [DIR filesep 'equations.txt'] rather than [DIR '/equations.txt'] or [DIR '\equations.txt']. If you type filesep on the command line, you’ll see that it returns ‘/’ if you’re running Mac OS, UNIX, or Linux and ‘\’ if you’re running Windows.

Let’s make a couple more improvements. First, 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 'ErrorMsg', 'popup' parameters in the pop_eegchanoperator() function to 'ErrorMsg', 'cw' so that error messages are printed in the Command Window and change 'Warning', 'on' to 'Warning', 'off' so that warning messages aren’t printed. (But note that error messages will still be printed.)

Now let’s make some changes that will have a more direct impact. First, we’re going to add _ref to the end of the name of the dataset to indicate that the data have now been referenced. Type EEG.setname on the command line so that you can see what the current setname is. If Subject 10 is the active dataset, 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_eegchanoperator command:

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

This takes the current setname and appends _ref to the end, storing the result in the EEG.setname variable. That was pretty easy! Note that this is right before the line with the eeg_store command, so the new setname will be stored in ALLEEG and therefore appear in the Datasets menu once we get to the eeglab redraw command. This line of code violates my rule about using variables to define values, because I didn’t define a variable for '_ref'. Rules are made to be broken, but only when there’s a good reason. In this case, the '_ref' string is something that I always use, so putting it into the body of the script is unlikely to cause problems later.

Now let’s add some code for saving the referenced dataset to your hard drive, in the same folder as the original dataset. You should first use the GUI to save the current dataset on your hard drive so that you can use the history to see the command for saving a dataset file. Select EEGLAB > File > Save current dataset as, and use tmp.set as the filename (in the Chapter_11 folder). Because you’re running this routine to see the history, you don’t actually need the file, and this filename will help you remember that it’s a temporary file that you can delete at some point. Now type eegh to see the history. You should see something like this:

EEG = pop_saveset( EEG, 'filename','tmp.set','filepath','/Users/luck/Ch_10_Scripting/Exercises/');

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 tmp.set. I like to have the filename be the same as the setname, but with .set on 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, replace the string that currently lists the path (which is '/Users/luck/Ch_10_Scripting/Exercises/' 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). Now you can run the new version of the script that changes the setname and saves the dataset as a file. If you get an error, or it doesn't seem to work correctly, you can fix it and try again. Once you get the script to work without any problems, you can comment out that line (i.e., add the % symbol) and run the script again to process all the subjects.

Now you have a robust, well-designed script that loads the datasets, references the data, saves the referenced data to your hard drive, and makes the datasets available in the EEGLAB GUI. 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).