~~ODT~~
====== EEG and ERPs Part 1 ======
Today we will begin lab exercise concerned with EEG and ERP recording and analysis. In today's lab, you will learn
how to carry out an ERP analysis.
Some relevant terminology:
* **EEG** means **electroencephalogram**, and refers to the continuously recorded voltage generated in the brain and from each electrode channel.
* An **Evoked Potential** or **EP** refers to a signal-average of EEG activity that is time-locked to a sensory event. We sometimes say Visual Evoked Potential, or VEP, to refer to the modality of the sensory stimulus.
* An **Event-Related Potential**, or **ERP**, refers to a signal-average of EEG activity that is recorded in response to a cognitive manipulation. For example, a potential that is recorded in response to viewing a word but not to a non-word would be referred to as an ERP.
Note, these are just conventions, and they were applied more firmly in the past then in the present. Many people now use EP and ERP interchangeably. EEG, ERPs, and EPs can be recorded non-invasively from electrodes on the scalp, or from electrodes placed directed in or on the brain. In situations where both are discussed, we sometimes say 'scalp-recorded EEG' to distinguish the former.
Data Acquisition terminology
* **ADC** analog to digital conversion.
* A/D sampling rate determines how finely we can slice up our samples in time
* A/D bits (e.g. 14 bit, 24 bit,etc) determines how finely we can slice up our voltage amplitude
* **Bandpass filter** determines which frequencies we allow to pass through without attenuation. For instance, a bandpass of .1 - 100 Hz would attenuate parts of the signal oscillating slower than 10 times per second (.1 Hz) or faster than 100 times per second (100Hz).
* **Gain** determines how much we amplify our referenced signal.
Stimulus Presentation terminology
* **Stimulus event code** The signal that is recorded into the EEG data that indicates the exact onset time of a stimulus
* aka event code, aka digital marker
* Usually different categories (e.g., faces, house) will have a different event code assigned to them.
* Faces = 1
* Houses = 2
* **Response code** is just like the stimulus event code, except that it marks the exact time the participant made a response.
===== Readings to be completed prior to this lab: =====
* none
===== Readings to be completed prior to next week's lab: =====
* none
===== Housekeeping =====
**1. ** Delete ''~/Desktop/input/eeg/Test_Data''
**2. ** Download the [[https://www.dropbox.com/s/07htvo225iduuss/eeg_lab2.zip?dl=0|''eeg_stuff.zip'']] from Dropbox.
* This is a ~400 MB file, so it might take a while to download depending on your internet speed.
**3. ** Double-click on the file ''eeg_lab2.zip'' in your ''Downloads'' directory to unzip it.
**4. ** Inside the unzipped ''eeg_lab2'' folder there will be three items:
* ''disp_single_trials_2020.m''
* ''eeglab2019_1''
* ''Test_Data''
**5. ** Move each of the files to their new homes. You can do this by dragging and dropping, or by using the following code in ''Terminal'' (remember to hit ''Enter'' after you paste each line of code)
# Move ''disp_single_trials_2020.m'' to the ''~/Desktop/scripts'' directory.
mv ~/Downloads/eeg_lab2/disp_single_trials_2020.m ~/Desktop/scripts
# Move the ''Test_Data'' directory into the ''~/Desktop/input/eeg'' directory.
mv ~/Downloads/eeg_lab2/Test_Data ~/Desktop/input/eeg/
# Move the ''eeglab2019_1'' directory into the ''~/Documents/MATLAB'' directory.
mv ~/Downloads/eeg_lab2/eeglab2019_1 ~/Documents/MATLAB
**6. ** Disable ''eegdeveloper'' Add-On
* Click on the ''Home'' tab (see image below)
* Click on the black down arrow underneath "Add-Ons" (see image below)
* Do **NOT** click on the three cubes above "Add-Ons"because this opens a different window.
{{:psyc410:images:addons.png?600|}}
* Select ''Manage Add-Ons''
* Find the ''eegdeveloper'' add-on in the list
* Select the three vertical dots at the very right of the row
* Uncheck "enabled"
* Close the window
**7. ** Edit your MATLAB startup file
* Open MATLAB
* At the MATLAB command line run the following code to open your ''startup.m'' file
edit ~/Documents/MATLAB/startup.m
You might get a warning that the file does not exist and a prompt asking if you want to create it. If so, click ''Yes''
**8. ** Add the following code to the ''startup.m'' file you opened in the last step.
addpath ~/Documents/MATLAB/eeglab2019_1
* Save and close the file ''startup.m''
* Run the file by typing the following in the command window
startup
**9. ** Test that everything is working
* Type which eeglab
* You should see ''/Users/hnl/Documents/MATLAB/eeg2019_1/eeglab.m''
* Let me know if you see anything else
* Now try opening ''EEGLAB'' by typing it on the command line
eeglab
* If things worked, EEGLAB will open
* If things didn't work, MATLAB will give you error
===== Goals for the laboratory exercise: =====
Our primary goal today is to learn how to analyze EEG/ERP data using **time domain** signal averaging. You will become familiar with the concepts of signal averaging, time-voltage waveforms, and voltage-space plots (topographies). You will then explore how scalp ERP fields can be modeled to visualize the brain regions that likely generate those scalp-recorded voltage-space plots.
There are two parts to today's lab:
- Use a simple Matlab script to observe signal averaging of an 'oddball' task (described below).
- Learn to analyze ERP data using ERPLAB
===== Software introduced in this lab: =====
We will use the analysis programs below for today's lab.
* [[http://sccn.ucsd.edu/wiki/EEGLAB_Wiki|EEGLab]] - a comprehensive toolbox of Matlab routines for analyzing EEG/ERP data.
* [[http://www.erpinfo.org/erplab.html|ERPLab]] - an ERP analysis toolbox that is integrated into EEGLab.
/*
* [[http://econnectome.umn.edu/|eConnectome]] - a program for calculating inverse models of EEG data so that cortical sources can be inferred.
*/
===== Data used in this lab =====
* For Part 1, we will be using data that were acquired in the Human Neuroscience Laboratory at Yale University.
* ''~/Desktop/eeg/oddball''
* For Part 2, we will be using data made available as part of the ERPLAB tutorial (described in more detail below.
* ''~/Desktop/eeg/Test_Data''
/*You will be looking at EEG data for three different tasks today. All data were acquired in the Human Neuroscience Laboratory at Yale University. Two data sets were collected using an older EEG acquisition system and a 32-channel headcap. The tasks included a simple **visual oddball** task and a **somatosensory evoked potential task (SSEP)**. The third data set was collected for a **visual evoked potential** task (VEP) on four different subjects using a newer EEG acquisition system and a 64-channel headcap. These tasks will be describe in the relevant sections below.
The EEG/ERP data acquisition computer records EEG continuously and logs the continuous EEG data to disk. The continuous EEG data files also contain trigger codes that are synchronized to the onset of different stimuli. The number value of the trigger code will be used to sort the stimuli into different bins for further analysis.*/
===== Laboratory Report =====
There is no lab report due next week. However, we will use the techniques learned this week to analyze the data from our next lab. **It is critical that you arrive to next week's lab comfortable with the methods you will learn tonight**
====== Part 1: Observing signal averaging - one trial at a time ======
One of the unfortunate aspects of modern analysis programs is that all of the interesting stuff happens inside the code and is unobservable to the operator. I want you to understand what is happening when we signal average data. We will therefore 'manually' create event-related averages from a simple "Oddball" experiment.
This section of the lab should help you appreciate how/why signal-averaging helps to reveal the underlying components that make-up the event-related potential.
===== The Oddball Task =====
The data we will look at were collected in an "oddball paradigm" composed of two visual stimuli (letter strings) that were rapidly presented in random order. The **XXXXX** stimuli were presented at 80% probability while the **OOOOO** stimuli were presented at the complementary 20% probability. The participant's task was to covertly count each time a **OOOOO** //target// stimulus was presented. This task is sometimes referred to as an **oddball** task due to the low probability and irregular appearance of the target stimulus. The oddball stimulus usually evokes a large [[https://en.wikipedia.org/wiki/P300_(neuroscience)|P300 ERP]] that, for simple visual stimuli, occurs 400-500 ms after the onset of the oddball. The frequent //standard// stimuli do not evoke a large P300, so comparing the target and standard will reveal the P300. The P300 is one of the first ERPs recognized to represent a cognitive process that was independent of the physical characteristics of the stimulus.
==== Data Acquisition Parameters ====
^Parameter^Value^
|EEG Sampling rate (i.e., A/D rate)|250 Hz|
|Bandpass| .1 Hz - 100 Hz|
|Gain| 20,000|
===== Program to Display Trial Data =====
You will use two ''.mat'' (the Matlab file format) datasets that are in ''~/Desktop/input/eeg/oddball''; one contains all of the //standard// trials, and the other contains all of the //target// trials.
We will use a very simple Matlab demo script (written by Greg McCarthy) named ''disp_single_trials_2020.m''. This program can be used to observe graphically the effects of signal processing.
**1.** Open ''Matlab'' and enter the following
edit '~/Desktop/scripts/disp_single_trials_2020.m'
The Matlab editor should open and you should see the code.
{{ :psyc410:images:matlab_disp_single_trials.jpg?nolink&0x600 |}}
The code progresses through the following stages:
* A file containing a series of single trials (either the //standard// or the //target// trials) is opened.
* Each single trial is read from the file and added to a summing array.
* An average is created by dividing the summing array by the current number of trials summed
* **__Stop and think about this for a second__**.
* All we are doing is calculating the mean of the single trials.
* We took the sum of all the single trials and divided by the total number of single trials.
* As we add a new trial, we update the mean.
* The average is thus updated and displayed as each new trial is added.
* A separate .mat is written for the frequent (//standard//) and rare (oddball, aka //targets//) conditions.
* The file names that include ''XXXXX'' contain the single peri-event epochs for //standards//
* The file names that include ''OOOOO'' contain single peri-event epochs for //targets//.
* "peri-event" simply means that the epoch was chose to include some time before (100 ms) and after (1000 ms) each event.
* The program first averages all of the frequent ''XXXXX'' stimuli, and then immediately starts averaging the rare oddball ''OOOOO'' stimuli.
===== What to Expect When You Run the Program =====
When you start the program (don't run it yet though) you will see a window similar to the one below.
{{ :psyc410:images:matlab_trial_data.png?nolink&600 |}}
**UPPER LEFT WINDOW:** a raw single trial epoch. This single trial contains the small time-locked ERP signal as well as the large EEG signal that is not time-locked to the stimulus event.
**UPPER RIGHT WINDOW:** contains the same single trial epoch as the upper left plot //except// that the average ERP has been subtracted from this trial. Thus, it represents an EEG residual that should contain no time-locked ERP 'signal'. Instead, it should display only the 'noise'.
**LOWER LEFT WINDOW:** contains the running average of the single trial epochs that appear in the upper left plot as the program advances.
**LOWER RIGHT WINDOW:** contains the running average of the single trial residual epochs that appear in the upper right plot as the program advances.
**Before proceeding ...** \\
* **Be sure you understand what is being displayed in each plot.**
* **Think about what you expect to happen in each of the four windows as you add more trials.**
- To start the program, press the run button to get the program/script going: \\
- (READ THE NEXT PART, ''Average Across More Trials'', BEFORE RUNNING THE SCRIPT) \\
{{:psyc410:images:matlab_run_button.png?nolink&400|}}
If you see the following box show up when you hit run, just select the ''Add to Path'' button.
{{ :psyc410:images:matlab_path_error.png?nolink&300 |}}
Make sure you click on the figure window that's created so that it's the "active" window.
You can edit the program to change what electrodes provide the data by changing the value of the ''display electrode'' variable on line 8. By default, it displays the ''Pz'' channel. This is a good channel for observing P300, but feel free to observe other channels. For example, the ''Oz'' channel is excellent for observing short latency visual evoked potentials, such as the P100. The program runs quickly, so you can see how P300 varies in amplitude across the scalp. As you will see later in this lab session, the distribution of voltage across the scalp is related to the location of the neurons in the brain that generate the ERP.
==== Average Across More Trials ====
To advance the program and look at more than 1 trial, hit any key (e.g., ''spacebar'') in the main Matlab window. Your plot will advance a given number of trials & update the signal average as it does so.
As the program advances, it adds the current single trial epoch to the average epoch below it. With increasing numbers of trials added (and averaged) the ERP signal should becoming increasingly clear in the lower left plot. \\
The program is set to stop at the squares of 1 through 12 trials (i.e., 1,4,9,16,25,36,49,64,81,100,121,144). Because the Signal-to-Noise ratio improves by the square root of the number of trials averaged, this allows you to observe your signal after SNR improvements of 1, 2, 3, 4, etc. \\
Just hit any key (e.g., ''spacebar'') to advance to the next integer squared. After trial 144, pressing any key will result in the program running all remaining trails.
* While watching the display, determine how quickly does the signal emerge from the noise?
* At what point does the signal stabilize and show little improvement when averaging additional trials?
* Compare the waveforms in the upper left and right columns.
* Can you actually see the difference due to the presence of the signal within the raw EEG?
* On some trials you can, but most of the time it is difficult. That is because the (ERP) 'signal' is much smaller than the (EEG) 'noise'.
The program will run automatically through the frequent (XXXXX) and rare oddball (OOOOO) data sets. At its conclusion, the program will create a new plot that shows the overlay of the final signal averages (ERPs) for the frequent XXXXXs (**blue line**) and rare oddball OOOOOs (**red line**). In this final plot, a more sensitive Y-axis microvolt scale will be used, so the ERPs will be plotted larger and more detail will be apparent.
{{ :psyc410:images:matlab_eeg_timeseries.png?nolink&400 |}}
* What distinguishes the ERP evoked by the rare oddball OOOOOs from the frequent XXXXXs?
* Can you see the P300?
====== Part 2: Creating ERPs with the ERPLAB suite ======
=== A few words about EEGLAB ===
[[http://sccn.ucsd.edu/eeglab/|EEGLab]] is a non-commercial, comprehensive EEG/ERP analysis program created at UC San Diego. ''EEGLab'' is a powerful program with many advanced features. Because ''EEGLab'' is written in Matlab and has an extensive function library, it is very easy to write Matlab scripts that call ''EEGLab'' functions. This allows labs to automate their procedures and simplifies the use of ''EEGLab''.
=== A few words about ERPLAB ===
//ERPLAB Toolbox is a free, open-source Matlab package for analyzing ERP data. It is tightly integrated with EEGLAB Toolbox, extending EEGLAB’s capabilities to provide robust, industrial-strength tools for ERP processing, visualization, and analysis. A graphical user interface makes it easy for beginners to learn, and Matlab scripting provides enormous power for intermediate and advanced users.//
In other words, once you've installed ERPLAB it basically works as if you've added extra features to EEGLAB. The goal is to give you an easy graphical interface to analyze ERP data.
===== Overview of this Tutorial =====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Overview-and-Scripting:-Tutorial|Overview and Scripting]]
This tutorial takes you step by step through the analysis of a set of ERP data from a subset of the subjects in a published experiment (Luck et al., 2009, Psychophysiology, 46: 776-786). It focuses on giving you experience with the specific steps involved in analyzing a simple prototypical ERP experiment. For details of the functions used here, see the [[https://github.com/lucklab/erplab/wiki/Manual|ERPLAB Toolbox User's Manual]].
This tutorial emphasizes using the GUI ("point and click") to process data. However, much of ERPLAB's power comes from the ability to write Matlab scripts. Each section therefore contains a box labeled Equivalent Script Command that shows how to achieve the same result with a line of script. More details about scripting can be found in the [[https://github.com/lucklab/erplab/wiki/Scripting-Guide|ERPLAB Scripting Guide]]. I've included these boxes for informational purposes so that you can see how you can achieve your goals using code instead of the GUI.
**You do not need to do anything with the code in the ''Equivalent Script Command'' boxes unless I specifically indicate otherwise.**
Note that script commands can also be run from the Matlab command line, which can be very useful. However, if you try to mix command line actions with GUI actions, you may run into trouble, because the GUI will not "know" about what you did on the command line. See the [[https://github.com/lucklab/erplab/wiki/Scripting-Guide|ERPLAB Scripting Guide]] for details.
===== Brief Description of the Example Experiment =====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Brief-Description-of-the-Example-Experiment:-Tutorial|Brief Description of the Example Experiment]]
The initial examples come from a published experiment. In this section, we will provide a basic overview of the experiment, along with a few of the details you will need to know to analyze it. For a complete description of the experimental paradigm, see the publication {{:psyc410:documents:Luck_2009.pdf|Luck et al., 2009, Psychophysiology, 46: 776-786}}.
This study examines the [[https://en.wikipedia.org/wiki/P300_(neuroscience)|P3 wave]] and the [[https://en.wikipedia.org/wiki/Lateralized_readiness_potential|lateralized readiness potential (LRP)]] in a group of schizophrenia patients and a group of matched control subjects. This tutorial focuses on the data from 6 of the control subjects (in the folders named S1 – S6). All subject identity information has been stripped from the data files.
==== Paradigm ====
In this experiment, a letter or digit was presented every 1300-1700 ms. Subjects were instructed to press a button with one hand for digits and with the other hand for letters. For a given trial block, either the letters or the digits were rare (20%) and the other category was frequent (80%). Thus, the stimulus category and the probability were counterbalanced. The probability manipulation was designed to isolate the probability-sensitive [[https://en.wikipedia.org/wiki/P3b|P3b component]]. \\
Different event codes were used for
* the digits when they were rare
* the digits when they were frequent
* the letters when they were rare
* the letters when they were frequent
* (The experiment also included a condition in which the two categories were equiprobable, but that condition is not included in this tutorial.)
The experiment was also designed to isolate the LRP by counterbalancing the stimulus category and probability with the left and right hand responses. That is, subjects responded to letters with the left hand and digits with the right hand for half of the experiment, and they responded to digits with the left hand and letters with the right hand for the other half. This is also indicated by the event codes for each stimulus (i.e., the event code for the stimulus also indicates the appropriate response for that stimulus).
ERPLAB Toolbox makes no distinction between stimulus event codes (i.e., the code sent concurrently with a stimulus) and response event codes (i.e, the code recorded concurrently with a participant's response). This gives the user more power, but it also gives the user responsibility for using the event codes in a sensible way. The event codes for responses in this example experiment indicated whether the response was correct (event code = 9) or incorrect (event code = 8) rather than directly indicating whether a left-hand or right-hand response was made. However, the combination of the stimulus event code and the response event code makes it possible to determine whether the subject pressed the left button or the right button.
Here is a table showing the stimulus event codes.
^ Event Code ^ Category ^ Probability ^ Correct Response ^
| 11 | Letter | Frequent | Left Hand |
| 21 | Digit | Rare | Right Hand |
| 112 | Letter | Rare | Left Hand |
| 122 | Digit | Frequent | Right Hand |
| 12 | Letter | Rare | Right Hand |
| 22 | Digit | Frequent | Left Hand |
| 111 | Letter | Frequent | Right Hand |
| 121 | Digit | Rare | Left Hand |
Letters and digits were presented in an unpredictable order within each trial block, but separate blocks were used for each combination of probability response assignment. That is, there were separate trial blocks for: (1) 80% letters (left-hand response) and 20% digits (right-hand response); (2) 20% letters (left-hand response) and 80% digits (right-hand response); (3) 80% letters (right-hand response) and 20% digits (left-hand response); (4) 20% letters (right-hand response) and 80% digits (left-hand response). Each block was originally recorded in a separate file.
==== EEG Data Acquisition ====
^Parameter^Value^
|EEG System|Neuroscan Synamps|
|ADC resolution|16-bits|
|EEG Sampling rate (i.e., A/D rate)|500 Hz|
|Bandpass| .05 Hz - 100 Hz|
|Reference| Right earlobe|
Recordings were also obtained from a vertical electrooculogram (VEOG) electrode located beneath the left eye and from an electrode on the left earlobe (both referenced to the right earlobe). A horizontal electrooculogram (HEOG) signal was recorded as the potential between electrodes located just lateral to each eye.
What do you know?
* Do you know a little bit about the P3 and LRP ERPs?
* Do you understand the design of this experiment?
* Do you understand how the event codes are used?
**Do not proceed until you answer "yes" to all of the above". You will not be successful in your next two lab reports without a thorough understanding of each of tonight's steps.** //Let me know if you're struggling.//
===== Getting Started =====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Getting-Started:-Tutorial|Getting Started]]
**1. ** Start EEGLAB
* Open Matlab.
* Navigate the current directory to the ''~/Desktop/input/eeg/Test_Data/S1'' folder.
* This is where the data from the first subject we will be processing is located.
* Enter the following into the command window
* cd ~/Desktop/input/eeg/Test_Data/S1
* In the Matlab command window, type the following (each line followed by the return/enter key):
clear all
eeglab
This will start you with a fresh EEGLAB and ERPLAB session.
For tonight's lab you will be saving your output files into the directory that contains the input files. In other labs we have avoided doing this, but for tonight's lab it's fine.
==== Load Dataset ====
^ Requirements ^ Completed? ^
| Loaded Data | |
| Creating an EventList | |
| Creating Bin-Based EEG Epochs | |
| Artifact Detection | |
| Creating Averaged ERPs | |
**2. ** In the EEGLAB menu bar, select ''File'' -> ''Load existing dataset''
* Select the file ''S1_EEG.set'' and click the Open button.
* Make sure EEGLAB is looking in the correct directory!
This will load the S1's data set into EEGLAB. The **S1_EEG.set** file is what EEGLAB calls a "dataset." The associated file, **S1_EEG.fdt**, contains the actual EEG data points and must be present (but it is accessed indirectly). The dataset contains a large amount of information, and EEGLAB may take several seconds to load the dataset.
Using EEGLAB and ERPLAB requires a little bit of patience. If you try to start the next procedure before the current procedure is done, you will cause problems that will ultimately slow you down. This is especially true during procedures that create or load datasets. So just take a sip of coffee and wait until you see "Done" in the command window before you take the next step.
**3. ** Confirm that the dataset has finished loading, by selecting the ''Datasets'' menu, as shown in the following screenshot:
{{ :psyc410:images:Tutorial_Getting-Started_2.png?nolink&600 |}}
Further confirmation that the ''S1_EEG.set'' has loaded can be found in the Matlab Command Window, EEGLAB will print an update on its current processing status. When the file has finished it will print "Done" (Both EEGLAB and ERPLAB print useful information such as this in the command window. Get in the habit of keeping an eye on this window.)
==== View Dataset ====
View the EEG data for the file you just loaded.
**1. ** In EEGLAB, select ''Plot'' -> ''Channel data (scroll)'' (See the [[https://sccn.ucsd.edu/wiki/EEGLAB_Wiki#The_EEGLAB_Tutorial_Outline|EEGLAB documentation]] for information on the Channel data (scroll) function).
{{ :psyc410:images:Tutorial_Getting-Started_3.png?nolink&800 |}}
**2. ** Click the ''>>'' button twice to scroll forward in time (10 seconds each click).
* Event codes (aka stimulus markers, trigger codes) will appear in the EEG plot as vertical lines with their corresponding numbers:
{{ :psyc410:images:Tutorial_Getting-Started_4.png?nolink&800 |}}
**3. ** Take a minute or two to get comfortable with the **Scroll channel activities** window. I often open this view before applying a routine, and then again afterward so that I can see what has been done to the data.
* What's on the x-axis?
* What's on the y-axis?
* Figure out how to change the axes. (the scale on x, and the scale on y)
* Note the values at the bottom of the screen that update as you hover the cursor in different locations.
* Etc.
Selecting an EEGLAB or ERPLAB command that puts up a window typically "locks up" Matlab so that other things won't work until that window has been dismissed. For example, you may not be able to open a text file with the Matlab text editor, or you may not be able to execute commands on the command line. Sometimes the open window is hidden by other windows. If you find that nothing seems to be working, take a look at Matlab's Windows menu to see if there are open windows that should be closed.
**Equivalent Script Command**:
% Load S1_EEG.set
% Filename is S1_EEG.set
% Note that you will need to replace the path with the actual location in your file system
% Make sure that your file names and folder names do not contain spaces or other special characters
% Note that the dataset will not appear in the Datasets menu in the EEGLAB GUI
EEG = pop_loadset('filename', 'S1_EEG.set', 'filepath', '../Test_Data/S1/');
%The following version will look for the file in Matlab's Current Folder
EEG = pop_loadset('filename', 'S1_EEG.set');
% To view the EEG data enter the following command:
pop_eegplot(EEG);
==== Add Channel Locations to Your Dataset ====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Adding-Channel-Locations-to-your-Dataset:-Tutorial|Adding Channel Locations to Your Dataset]]
Before we start using ERPLAB's functions, we'll use one of EEGLAB's functions that will prove useful at a later stage. Specifically, we will add location coordinates for each electrode site (see the [[https://sccn.ucsd.edu/wiki/Chapter_02:_Channel_Locations|EEGLAB documentation]] for more information). Our original data file contained electrode labels conforming to the [[https://en.wikipedia.org/wiki/10%E2%80%9320_system_(EEG)|International 10/20 System]], and EEGLAB can automatically determine standard coordinates on the basis of these labels. These coordinates are not guaranteed to be exact, but they are a reasonable approximation for simple procedures such as plotting scalp maps.
**1. ** To add coordinates based on the electrode labels, select ''Edit'' -> ''Channel locations'', which will bring up the window shown here:
{{ psyc410:images:Tutorial_Adding-Channel-Locations_1.png?600 }}
**2. ** Click ''Ok'', and you will see the window shown here:
{{ psyc410:images:Tutorial_Adding-Channel-Locations_2.png?600 }}
**Equivalent Script Command**:
%Adding Channel Locations to Dataset
%Make sure that you change the path to indicate the location of eeglab within your file system
EEG=pop_chanedit(EEG,'lookup',
'/Users/etfoo/Documents/MATLAB/eeglab9_0_2_3b/plugins/dipfit2.2/standard_BESA/standard-10-5-cap385.elp');
**3. ** For simple data files such as the one used in this tutorial, you can accept all of the default values and simply click ''OK''. This will add the coordinates to the current dataset.
**4. ** Test that channel locations have been successfully added. EEGLAB and ERPLAB require electrode coordinates for plotting topographic maps; you will get an error message if you try to plot a topographic map before you've added the coordinates. You can verify that the coordinates have been added by running a routine that plots topographic maps. For example, if you select ''Plot'' -> ''Channel spectra and maps'' and select the default parameters in the window that appears, as shown in the screenshot below:
{{ psyc410:images:Tutorial_Adding-Channel-Locations_3.png?600 }}
**5. ** Click ''OK'' and you will see the following plot:
{{ psyc410:images:Tutorial_Adding-Channel-Locations_4.png?600 }}
Though we just created this plot to test our channel locations, you might be curious as to what is being displayed. This plot is showing the distribution of power across the scalp for 6 Hz, 10 Hz, and 22 Hz. In other words, this plot shows us that electrodes toward the back of the scalp have a lot of power at 10 Hz (which makes sense if we remember the "Berger rhythm", but not at 22 Hz.
**Equivalent Script Command**:
%Plot Channel Spectra and maps
figure; pop_spectopo(EEG, 1, [0 2139038], 'EEG' , 'percent', 15, 'freq', [6 10 22], 'freqrange',[2
25],'electrodes','off');
**6. ** Later parts of this tutorial will make use of this dataset, so you should save it to disk. First, however, you should change the name of the dataset to ''S1_Chan'' so that you can differentiate between this version and the original version.
* Select ''Edit'' -> ''Dataset info''. This will bring up the window shown below.
* Enter ''S1_Chan'' in the ''Dataset name'' field.
* Click ''OK''.
* Look in the ''Datasets'' menu. You should now see that it is named S1_Chan.
{{ psyc410:images:Tutorial_Adding-Channel-Locations_5.png?600 }}
**7. ** You can now save the modified dataset by selecting ''File'' -> ''Save current dataset as''. We recommend that you give the file the same name as the dataset, but with a .set extension (e.g., **S1_Chan.set**).
**Equivalent Script Command**:
%Setname is S1_Chan
%Filename is S1_Chan.set
%Path is /Users/etfoo/Desktop/tutorial_script/
%Note that you will need to replace the path with the actual location in your file system
EEG.setname='S1_Chan';
EEG=pop_saveset(EEG, 'filename', 'S1_Chan.set', 'filepath', '/Users/etfoo/Desktop/tutorial_script/');
%Alternatively, the following version will put the file in Matlab's Current Folder
EEG.setname='S1_Chan';
EEG=pop_saveset(EEG, 'filename', 'S1_Chan.set');
What do you know?
* Do you understand why the channel locations need to be assigned in order to plot topographical maps like the one you plotted in this section?
**Do not proceed until you answer "yes" to all of the above". You will not be successful in your next two lab reports without a thorough understanding of each of tonight's steps.** //Let me know if you're struggling.//
===== Background Concepts: Datasets, ERPsets, and Bins =====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Background-Concepts:-Datasets,-ERPsets,-and-Bins:-Tutorial|Background Concepts: Datasets, ERPsets, and Bins]]
There are a few key concepts you need to understand before we go any further.
=== Dataset ===
EEGLAB stores a set of EEG data in something called a dataset. A dataset typically stores the data from a single subject, either a single block of trials or an entire session. A dataset is maintained in memory inside EEGLAB, and it can also be saved on disk. Whenever you run a routine that changes the data in a dataset, a new dataset is created. You can see the currently available datasets in the ''Datasets'' menu. One dataset is currently active, and any routines that you run will typically be applied to the current dataset. When a new dataset is created, it becomes the current dataset, but you can make a different dataset active by selecting it in the ''Datasets'' menu. This provides a very convenient workflow.
=== ERPset ===
ERPLAB defines an analogous structure called an ERPset, which stores a set of ERP waveforms. They can be active inside ERPLAB and/or saved to disk. The ''ERPsets'' menu can be used to see which ERPsets are currently loaded into ERPLAB and to change which ERPset is active.
=== Bin ===
A //bin// is a set of averaged ERP waveforms, one for each electrode site, which were created by averaging together a specific set of EEG epochs. A simple oddball experiment, for example, might have one bin for the infrequent targets and another bin for the frequent standards. However, a sophisticated experiment might have dozens of different bins, with a given bin being something like "Digits preceded by letters followed by a correct response between 200 and 1000 ms, in a condition in which digits are rare and letters are frequent." In many ERP analysis systems, a bin would be equivalent to a single averaged ERP file. However, this can lead to a huge number of different files for each subject, making it difficult to keep track of everything. In ERPLAB, an ERPset can contain an unlimited number of bins), and each data processing operation is typically applied to all of the bins in the currently active ERPset. This saves time and reduces errors.
===== Creating An Eventlist =====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Creating-an-EventList:-ERPLAB-Functions:-Tutorial|Creating An EventList]]
^ Requirements ^ Completed? ^
| Loaded Data | ✓ |
| Creating an EventList | |
| Creating Bin-Based EEG Epochs | |
| Artifact Detection | |
| Creating Averaged ERPs | |
We are now ready to get into the ERPLAB functions. We will begin with some housekeeping, then do artifact rejection, and finally averaging.
The event codes are embedded in a dataset within EEGLAB's EEG structure, which is pretty complicated. To make it easier to see and manipulate the event codes, **ERPLAB creates an EventList, which is a list of all of the event codes and associated information**. The the EventList can also be saved in a text file, where you can easily see and manipulate the event information. If you make any changes, you can import it back into the EEG structure.
/*
**1.** To use ERPLAB, first create an EventList for the EEG stored in your dataset.
* In the ERPLAB menu, select ''EventList'' -> ''Create EEG EVENTLIST''. (A warning may popup warning you that some of all of your events contain an event-based event label, and not a numeric event code. For now, ignore it and click the ''Continue'' button).
* The following popup window titled ''Create Basic EventList'' GUI will appear:
{{ :psyc410:images:Tutorial_Creating-an-EventList_1.png?600 | }}
**2.** Check the option ''Export EventList to text file'' and enter the filename: ''elist.txt''. To save to a specific folder location, click the ''Browse'' button. Otherwise, the elist.txt file will be save to Matlab's current directory. We are having you export the EventList as a text file in this example so that you can see the contents of the EventList that you're creating; for most real experiments, you will not select this option.
**3.** Check the option ''Create numeric equivalents of nonnumeric event codes when possible'' (e.g., S12 becomes 12). Some systems (e.g., EGI and Brain Products) use text strings rather than numeric values as event codes. In some systems, this is very subtle (e.g., the codes might be 'S21', which looks like a number but isn't). You must convert these to numeric values, which can usually be accomplished with this option. This can also be accomplished with a script function called letterkilla. From the Matlab command window or a script, you will type EEG = letterkilla(EEG); You can then type eeglab redraw to make the updated dataset available from the EEGLAB GUI. However, these two options will be insufficient if your event labels do not have numbers in them (e.g., 'target'), or if you have different event codes that contain the same numbers (e.g., 'S1' and 'R1'). In these cases, you should instead use the advanced options in Create EventList, as described next.
**4.** Click the ''Create'' button to create the EVENTLIST. This will create the EVENTLIST structure, add it onto the current EEG structure and creating a new dataset. Any operation that creates a new dataset will put up the window as shown below, which gives you some options for saving the new dataset. First, you need to specify a name for the new dataset. This name will be stored inside the dataset, and it will be shown in the ''Datasets'' menu. It is not necessarily the same as the name of the file in which the dataset is stored on disk, but we recommend that you use the same name for the file (if you save it as a file on disk). ERPLAB will automatically suggest a name for the dataset, appending a string onto the end of the name of the dataset from which the new dataset was created.
When an EventList is generated, it suggests adding ''_elist'' onto the dataset name (going from ''S1_Chan'' to ''S1_Chan_elist''). This is not required, but it is recommended (otherwise you will have a hard time remembering what is in a given dataset. If you check the ''Save it as file'' button and use the ''Browse'' button to select a filename, the dataset will be saved to disk. You can also choose to either keep the previous dataset in the ''Datasets'' menu (this is the default) or overwrite the previous dataset in this menu.
{{ :psyc410:images:Tutorial_Creating-an-EventList_2.png?600 | }}
It is good practice to save the dataset to disk after you've gone through several steps; otherwise all your work will be lost if the program crashes. And you should obviously save to disk if you are going to quit the program and you don't want to lose what you've created. However, it usually isn't necessary to save every dataset you create – this ends up leading to a lot of big files on your hard drive. Also, we don't usually overwrite the previous dataset, because then we can't easily back up to the previous step. However, there are no hard-and-fast rules here; you will eventually develop a set of habits that make sense for your own needs.
There are two ways to see the EventList that you just created:
**1.** The first way is to type ''EEG.EVENTLIST'' in the Matlab command window. Doing so, will display following in the Matlab Command window:
{{ :psyc410:images:Tutorial_Creating-an-EventList_3.png?600 | }}
If you have some Matlab experience, you can drill further into this structure to see what it contains.
**2.** The second (easier) way is to open the text file that you created (elist.txt) in Matlab's text editor. When it was created, ERPLAB put a link to the file in the Matlab command window, as shown by the underlined blue text in the following screenshot. Click on this link and the file will open.
{{ :psyc410:images:Tutorial_Creating-an-EventList_4.png?600 | }}
Take a look at this file to see that it has all the event code information.
**Equivalent Script Command**:
% Create an EventList, saving a text version in a file named 'elist.txt' in Matlab's current folder
EEG = pop_creabasiceventlist( EEG , 'Eventlist', 'elist.txt', 'BoundaryNumeric', { -99 } ...
, 'BoundaryString', { 'boundary' }, 'Warning', 'on' );
*/
==== Advanced EventList Options ====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Advanced-EventList-Options:-Tutorial|Advanced Eventlist Options]]
When you create an EventList, you can add some additional information using the ''ADVANCED'' button in the ''Create EventList window'' (see screenshot below). The ''ADVANCED'' tools are important if you have complex text-based event labels (or want to create them) or if you have a very simple scheme that links event codes to bins. Most people won't use the ''ADVANCED'' button, but it is important for the present tutorial.
The ''ADVANCED'' button allows you to define a text label for each numeric event code (or vice versa), which helps to avoid the errors that often occur in experiments with many different event codes. It also allows you to define the bins that you will use to sort your EEG epochs for averaging.
**1.** Make sure that ''S1_Chan'' is selected as the active dataset in the ''Datasets'' menu (because we are going to re-create the eventless).
* Select ''ERPLAB'' -> ''EventList'' -> ''Create EEG EventList''.
* You might get a yellow warning window about numeric codes. If so, just click ''Continue''.
{{ :psyc410:images:tutorial_advanced-eventlist-options_1.png?600 |}}
**2.** Click the ''Advanced'' button to open the ''Create Advanced EventList'' window.
{{ :psyc410:images:tutorial_advanced-eventlist-options_2.png?600 |}}
The ''Create Advanced EventList'' panel allows you to define a set of events for the experiment. Each event contains a numeric event code and text-based event label, as well as an optional bin number and bin label.
/*
Note: ERPLAB requires that each event has a numeric event code. If your data acquisition system uses text-based labels instead of numeric codes, you must define a numeric event code for each text-based event label. If your data acquisition system uses numeric codes, you are not required to create text-based labels for each code, but it can be useful to help remember what each numeric event code means. You can also define a bin for all (or some) of your event codes, along with a label for that bin. We will do that in this example, but it is not necessary if you will be using BINLISTER in a later step to define your bins.
*/
=== Define Event Codes ===
**3.** Define this information for a single trial block from our example experiment. Enter the following information into the ''Event Info'' area (upper right corner) of the ''Create Advanced EventList'' window:
|Event Code:|22|
|Event Label:|Frequent_Digit|
|Bin number:|1|
|Bin description:|Frequent Category (digit)|
**4. ** Click the ''Update Line'' button to add the event information to the **Currently edited eventcodes list** (left pane).
* For each event, the **Event Info** area defines the event codes, event labels, bin numbers, and bin descriptions for each event.
* In our experiment, letters were rare (event code 12) and numbers were frequent (event code 22).
**5.** Next, define the //rare letter event//. Click on the ''new line'' entry in the ''Currently edited eventcodes'' pane. Enter the following information for the rare letter event:
|Event Code:|12|
|Event Label:|Rare_Letter|
|Bin number:|2|
|Bin description:|Rare Category (letters)|
Don't forget to click ''Update Line'' after entering the information for each type of event or the information will not be added to the table.
Your bin numbers must start at 1 and be consecutive with no breaks (the event codes need not be consecutive, and they can be any integer number that Matlab can represent).
=== Define Response Codes ===
It will still be useful to define labels for the response codes so that we will not have to remember that code 9 denotes a correct response and code 8 denotes an incorrect response. The table below shows how to define these events.
|Event Code:|9|Event Code:|8|
|Event Label:|Corr_Resp|Event Label:|Err_Resp|
|Bin number:|(blank)|Bin number:|(blank)|
|Bin description:|(blank)|Bin description:|(blank)|
**6.** Save the event code equation list in the Equation List pane (bottom-left)
* Click on the ''Save list'' button
* Navigate to your save directory and type in the filename: ''elist_equations.txt''
* Click the ''Save'' button. The save file name and path should now appear in the Equation List pane.
{{ :psyc410:images:tutorial_advanced-eventlist-options_3.png?600 |}}
You will need to do this step for every subject. But because the event and response codes are the same for all subjects in a given experiment, you can simply load the ''elist_equations.txt'' file for all subsequent subjects.
**7.** Save the EventList in a text file (to look at it later) Locate the ''Write resulting EVENTLIST'' pane in the bottom-right corner
* Check the box labeled ''Text File''
* Click the ''Browse button'' to save the file as ''elist.txt''. (The .txt extension is not required, but it's a good idea)
* Check the box labeled ''Transfer EVENTLIST info to EEG.event'' if it's not already checked.
EEGLAB keeps track of event information in the EEG.event structure, but EEGLAB doesn't automatically "know" anything about ERPLAB's EventList. Moreover, the EEG.event structure can store either a numeric event code or a text-based event label for a given event, but not both. By checking this box, you will have the opportunity to transfer your newly created labels into EEG.event so that they will be available for use by EEGLAB functions (such as the function for plotting the EEG data).
**9.** Apply the EventListClick the ''APPLY'' button to create the EventList and add it to the current ERP dataset.
The information about event mapping must be stored in a file. Therefore, if you have made any changes in this information, the following window will appear:
{{ :psyc410:images:tutorial_advanced-eventlist-options_4.png?600 |}}
**10. ** Click on the ''Save and Continue'' button to create the EventList. Because we have checked the Transfer EVENTLIST info to EEG.event box), the following window will appear:
{{ :psyc410:images:tutorial_advanced-eventlist-options_5.png?600 |}}
This window allows you to choose whether to store the events as event codes, event labels, or bin numbers in the EEG.event structure). The default is Code Labels, and selecting this will allow you to see the labels for each event code when you look at the EEG using EEGLAB's ''Plot'' -> ''Channel data (scroll)'' routine. Keep the default Code Labels setting and click the ''APPLY'' button.
ERPLAB will then attach the EVENTLIST structure that you just created to the current dataset to produce a new dataset. Any operation that creates a new dataset will put up the save dataset window shown in the next screenshot.
**Equivalent Script Command:**
% The first step is to create a file named elist_equations.txt with the following contents:
% 22 "Frequent_Digit" 1 "Frequent Category (Digit)"
% 12 "Rare_Letter" 2 "Rare Category (Letter)"
% 9 "Corr_Resp" [] ""
% 8 "Err_Resp" [] ""
%
% The following command creates the event list using these equations, using a fully specified path
% A text file with the event list saved in elist.txt in the same path
EEG = pop_editeventlist(EEG,'/Users/etfoo/Desktop/tutorial_script/elist_equations.txt', 'elist.txt', {'boundary'}, {-99});
% The following command uses Matlab's Current Folder
EEG = pop_editeventlist(EEG,'elist_equations.txt', 'elist.txt', {'boundary'}, {-99});
% Copy event labels into the EEG structure
EEG = pop_overwritevent( EEG, 'codelabel');
**11.** Specify a name and save your new dataset
* Check the ''Save it as file'' box
* Click the ''Browse'' button and select a save directory
* Specify the filename ''S1_Chan_elist''
* click the ''Save'' button
This name will be stored inside the dataset, and it will be shown in the ''Datasets'' menu.
The dataset name is not necessarily the same as the file in which the dataset is stored on disk, but we recommend that you use the same name for the file (if you save it as a file on disk). ERPLAB will automatically suggest a name for the dataset, appending a string onto the end of the name of the dataset from which the new dataset was created. When an EventList is generated, it suggests adding "_elist" onto the dataset name (going from "S1_Chan" to "S1_Chan_elist"). This is not required, but it is recommended (otherwise you will have a hard time remembering what is in a given dataset.
The dataset will then be saved to disk. You can also choose to either keep the previous dataset in the ''Datasets'' menu (this is the default) or overwrite the previous dataset in this menu.
{{ :psyc410:images:tutorial_advanced-eventlist-options_6.png?600 |}}
**12. ** You should save the new dataset to a file, named ''S1_Chan_elist.set'', but don't overwrite the old dataset. Click ''OK'', and the new dataset will be created (this may take a few seconds). Once the new dataset has been created (you will see "Done" printed in the Matlab command window), you will be able to see it in the ''Datasets'' menu, as shown in the next screenshot.
{{ :psyc410:images:tutorial_advanced-eventlist-options_7.png?600 |}}
**Equivalent Script Command:**
% Saving after Eventlist
% Setname is S1_Chan_elist
% Filename is S1_Chan_elist.set
% Path is /Users/etfoo/Desktop/tutorial_script/
% Note that you will need to replace the path with the actual location in your file system
EEG.setname='S1_Chan_elist';
EEG=pop_saveset(EEG, 'filename', 'S1_Chan_elist.set', 'filepath', '/Users/etfoo/Desktop/tutorial_script/');
% The following command uses Matlab's Current Folder
EEG.setname='S1_Chan_elist';
EEG=pop_saveset(EEG, 'filename', 'S1_Chan_elist.set');
What do you know?
* What did you do in this section?
* Be sure you understand how event and response codes are used and how they are different from bins and bin numbers.
* Do you understand the difference between an **event code** and a **bin number**?
**Do not proceed until you answer "yes" to all of the above". You will not be successful in your next two lab reports without a thorough understanding of each of tonight's steps.** //Let me know if you're struggling.//
==== Verify your event codes ====
**1.** You will now be able to see that the previous event code numbers have now been replaced by their event labelsIn EEGLAB, select ''Plot'' -> ''Channel data (scroll)'' and scroll ahead to the period starting at 10 seconds (hit the ''>>'' button twice)
{{ :psyc410:images:tutorial_advanced-eventlist-options_8.png?600 |}}
The standard EEGLAB routine only provides room for about 10 characters, so some of the labels are truncated.
**2** //Optional//: You can modify the number of characters shown in the plotting function.
* Within the plotting window, select ''Settings'' > ''Events'' > ''Events'' ''String Length''
* Note: Do this within the plotting window and not from the main EEGLAB window
* Enter a width of 20 characters to make the plot will look like this:
{{ :psyc410:images:tutorial_advanced-eventlist-options_9.png?600 |}}
**3.** View the data.
* Scroll through the data for a while.
* You might want to change ''Settings'' -> ''Time range to display'' to 30 seconds (within the plotting window).
* Eventually (around 120 seconds) you will see a period with no event codes and lots of artifacts. This is a short rest break about ¼ of the way through the trial block. You'll see another period like this at 255 seconds and 390 seconds.
* The trial block ended at approximately 525 seconds and the file ended at 535 seconds. You will see a boundary event label at this point, which is where the second trial block was appended after the first trial block.
/*If you keep going past the boundary event, you will start to see some numeric event codes. In this simplified example of creating an EventList, we assigned labels only to the event codes for the stimuli that were used in the first block of trials (along with the responses for the entire session). You don't need to assign labels for all of your event codes (or even any of them). However, having the labels makes it much easier to link the signals that you see in the EEG to specific types of events (especially in experiments with dozens of different event codes).*/
If you're interested, you can take a look at the text version of the EventList that you created. Simply open this file with the Matlab text editor. For details on the contents and format of this file, see the ERPLAB User's Manual. Later on we will show how you can edit this file and import it back into your EEG data.
===== Creating Bin Based EEG Epochs =====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Creating-Bin--Based-EEG-Epochs:-Tutorial|Creating Bin Based EEG Epochs]]
^ Requirements ^ Completed? ^
| Loaded Data | ✓ |
| Creating an EventList | ✓ |
| Creating Bin-Based EEG Epochs | |
| Artifact Detection | |
| Creating Averaged ERPs | |
The next step after creating the EventList is usually to sort the events into different bins (in preparation for averaging). However, we already did this by assigning bins for the rare and frequent stimuli when we created the EventList using the Advanced button.
Once the events have been assigned to bins, the next step is to divide the continuous EEG into a set of fixed-length epochs (aka segments or sweeps), each of which is time-locked to an event that has been assigned to a bin. In the present example, we will extract the EEG during a period that begins 200 ms prior to the onset of a stimulus and ends at 800 ms after the onset of the stimulus. This will be done for each event code that has been assigned to a bin (which is, in the present example, the frequent letters and rare digits, but not the responses).
EEGLAB has an epoching function (''Tools'' -> ''Extract epochs''); you should not use this function if you are using the ERPLAB functions for processing the epochs (e.g., averaging, plotting, etc.).
**1. ** In ERPLAB, select ''ERPLAB'' -> ''Extract Bin-based Epochs''. This will open the ''Extract Bin Epochs window'':
{{ :psyc410:images:Tutorial_Creating-Bin-Based-EEG-Epochs_1.png?600 | }}
**Equivalent Script Command:**
% Create Bin-Based EEG Epochs
% Extracts bin-based epoch from -200 ms to +800 ms
% 'pre' means use the prestimulus period for baseline correction
% Use 'post' to use the poststimulus period for baseline correction
% Use 'all' to use the poststimulus period for baseline correction
% Use two numbers in quotes (e.g., '-150 +50') to specify a custom interval for baseline correction
EEG = pop_epochbin( EEG , [-200.0 800.0], 'pre')
The ''Extract Bin Epochs'' window allows you to select the time period for the epoch (relative to the event code). Baseline correction will be enabled by default (see box below), and you will almost always want to do this. The prestimulus period (''Pre'') is usually the period used for baseline correction. Alternatively, you can use the poststimulus interval (''Post''), the entire interval (''Whole''), or some time range of your choice (''Custom'').
Baseline correction is used so that we can compare the //relative// change in voltage from one trial to another. The baseline correction ensures we are subtracting any non-stimulus effects.
Suppose I wanted to compare my height to yours with a tape measure that is attached to the floor. Now suppose I'm standing on a 12" pedestal and you're standing on a 15" pedestal. In order to get a fair comparison of our heights we would want to subtract 12 from my height and subtract 15 from your height.
If we indicate ''PRE'', we are indicating that the average voltage during the //prestimulus// period for a given trial is subtracted from every point in the epoch. This is done independently for each channel.
**2. ** For this example, leave ''Pre'' as selected.
* Click the ''RUN'' button
* A new dataset with the epoched data will be created (it will take a few seconds). The standard window for saving a new dataset will appear.
{{ :psyc410:images:Tutorial_Creating-Bin-Based-EEG-Epochs_2.png?600 | }}
**3. ** By default the new dataset will be named''S1_EEG_elist_be'' ("be" stands for bin-epoched).
* Click the checkbox next to ''Save it as a file'' and then click ''Browse''
* Enter the filename ''S1_EEG_elist_be''
* Click ''Ok''
**Equivalent Script Command:**
% Saving after Epoching
% Setname is S1_EEG_elist_be
% Filename is S1_EEG_elist_be.set
% Path is /Users/etfoo/Desktop/tutorial_script/
% Note that you will need to replace the path with the actual location in your file system
EEG.setname='S1_EEG_elist_be'
EEG=pop_saveset(EEG, 'filename', 'S1_EEG_elist_be.set', 'filepath', '/Users/etfoo/Desktop/tutorial_script/');
% The following command uses Matlab's Current Folder
EEG.setname='S1_EEG_elist_be';
EEG=pop_saveset(EEG, 'filename', 'S1_EEG_elist_be.set')
**4. ** Make sure that this new dataset is the active dataset (by looking in the ''Datasets'' menu).
* Select ''Plot'' => ''Channel data (scroll)''.
The following screen shows what it should look like. There should still be continuous EEG data, but if you look more closely you will see a vertical dashed line 800 ms after (and 200 ms before) each event. This dashed line marks the end of one epoch and the beginning of the next. If you find this disconcerting, you can simply change ''Settings'' -> ''Time range to display'' to a period of 1 second (in the plotting window).
EEGLAB routines typically ask you to enter time information in seconds, whereas ERPLAB routines typically ask for milliseconds.
{{ :psyc410:images:Tutorial_Creating-Bin-Based-EEG-Epochs_3.png | }}
Because the epoch length in this experiment is shorter than the interval between consecutive stimuli, the epoched data will now be missing a period of time between the end of one epoch and the beginning of the next epoch. If, however, we used a 2000-ms epoch length, the last part of one epoch would contain the same EEG data as the beginning part of the next epoch.
What do you know?
* What did we just do to the EEG data?
* How does this "epoched" data differ from the continuous EEG data?
**Do not proceed until you answer "yes" to all of the above". You will not be successful in your next two lab reports without a thorough understanding of each of tonight's steps.** //Let me know if you're struggling.//
===== Artifact Detection =====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Artifact-Detection:-Tutorial|Artifact Detection]]
^ Requirements ^ Completed? ^
| Loaded Data | ✓ |
| Creating an EventList | ✓ |
| Creating Bin-Based EEG Epochs | ✓ |
| Artifact Detection | |
| Creating Averaged ERPs | |
The next step after epoching is usually artifact detection. ERPLAB makes a distinction between artifact detection and artifact rejection.
* **Artifact __detection__ is the process of __marking__ epochs that contain artifacts.**
* **Artifact __rejection__ is the process of __excluding__ trials containing artifacts**.
The ERPLAB artifact detection routines do not throw out any data; epochs with artifacts are merely marked. Artifact rejection occurs during averaging; marked epochs are simply excluded from the averaging process.
There are lots of different ways to define artifacts. Some require expert eyeballs manually reviewing the data, whereas others rely on automatic algorithms. Below, we'll try a couple such algorithms.
What is an artifact?
An artifact is a change in signal caused by an event that we are not interested in. In other words, noise. However, when referring to artifacts we are generally referring to large and discreet changes in the waveform (e.g., an eye blink) rather than any continuous non-event related signal (e.g., day dreaming about weekend plans). Artifacts are almost always much bigger than our signal of interest; they can easily be an order of magnitude bigger. Because they are so large, they're likely to stick around and muck things up even after we've done our signal averaging (*see below). So it's very important that we try to identify and remove them.
* Think of a simple numerical example in which we've sampled 100 events. 99 of the events yielded a value of ''5'' (the events and the numbers are arbitrary). On one event somebody tripped over a power cord or some such thing and we recorded a value of ''5000''. "No problem, right? That's why we do signal-averaging". But if we do the math you'll see that the single artifactual event really screws things up. We know that the average should be ''5'', but if we calculate the mean of our 100 trials -- ((99*5) + 5000)/100 -- we get an average value of **545**!!
/* EEGLAB provides a method for manually rejecting (deleting) sections of the EEG data, and ERPLAB contains a method for automatically finding sections of "crazy" data and rejecting (deleting) them. However, we strongly recommend that you use these only when it is absolutely necessary to delete the sections of EEG (e.g., deleting "crazy" data periods prior to ICA), and that you use artifact detection (marking of artifacts) for dealing with artifacts in all other cases. Also, note that the deletion of sections of the EEG also leads to deletion of the event codes within those sections. Consequently, if you are going to delete sections of EEG (with any method), you must do so before the EVENTLIST has been created. In contrast, artifact detection should typically be conducted as the final step before averaging.*/
==== Example 1: Moving window peak-to-peak threshold ====
We will start with **moving window peak-to-peak threshold**.
**1. ** Make sure that your epoched dataset is active ("S1_EEG_elist_be")
**2. ** Select ''ERPLAB'' -> ''Artifact detection in epoched data'' -> ''Moving window peak-to-peak threshold''.
* You will see the window shown in the screenshot below.
{{ :psyc410:images:Tutorial_Artifact-Detection_1.png?600 |}}
This routine finds the maximum peak-to-peak voltage within a moving window that slides across the epoch (see the ERPLAB User's Manual for details). You select the **Test period**, which is by default the entire epoch. However, sometimes you will want to search for artifacts only during a portion of the epoch.
You must also choose a **Voltage threshold**. An epoch will be rejected if the peak-to-peak voltage (the difference between the largest and smallest values) exceeds this value. The appropriate value will depend on the nature of the artifact you are trying to reject and how large it is in a given subject (see Chapter 4 in //An Introduction to the Event-Related Potential Technique// for an overview of artifact detection).
You will then choose the length of the **Moving window** and the **Window step**. This routine finds the peak-to-peak voltage within a window of the length specified in the **Moving window** field. It then shifts the window by the amount specified in the **Window step** field and finds the peak-to-peak voltage within this new window. This is repeated until the end of the **Test period**, and the largest of these peak-to-peak amplitudes is compared with the **Voltage threshold**. This is an excellent way to find artifacts in which the voltage changes rapidly within a relatively short period of time (e.g., blinks, which usually peak and then subside within 200-300 ms) and not be fooled by relatively slow voltage changes.
By default, artifacts will be detected in all channels. However, you can specify a subset of channels to be tested in the **Channel(s)** field.
Most windows that ask you to specify a range of values allow you to use the standard Matlab rules for numeric lists. You can simply type the values separated by spaces (e.g., "1 2 3"), or you can use a colon to specify a range (e.g., "1:3") or some combination (e.g., "1:3 5:7" to indicate 1-3 and 5-7). To specify a regular set of values, you can specify the first value, the step size, and the last value (e.g., "1:3:7" to start with 1 and go by steps of 3 to a final value of 7 [1 4 7]).
/*Finally, you can specify a set of flags in the **Flag** field that will be set in the EventList whenever an epoch has been marked for rejection. This allows you to do things like perform behavioral analyses on the information in the EventList while excluding events that contain artifacts. Flag 1 is always set for events with artifacts, and you can keep track of which events had which types of artifacts by setting additional flags for each artifact rejection test you perform. For details, see the ERPLAB User's Manual.*/
**3. ** Set all of the fields as shown in the screenshot above (including ensuring the ''Open viewer'' box is checked)
* Click on **Mark Flag** ''4''
* Click ''Accept''
ERPLAB will then scan the active dataset for artifacts (which may take some time). The total percentage of trials with artifacts detected (i.e., the total percentage marked for rejection, including epochs that had been marked previously) will be shown in the Matlab command window:
pop_artmwppth() rejected a 29.7 % of total trials.
At this point, the ERPLAB artifact rejection routines automatically bring up the scrolling EEG data viewer window, as shown in the screenshot below.
**4. ** Scroll through the data to make sure that the parameters you entered have actually caused epochs containing artifacts to be detected without accidentally marking a large number of epochs without true artifacts.
* For example, you may need to increase the threshold if epochs without real artifacts are being marked for rejection, and you may need to decrease the threshold if epochs with clear artifacts are not being marked.
* Each epoch that has been marked is shown with a yellow background, and the channels within the epoch that exceeded the rejection threshold are drawn in red (see screenshot below).
* Artifact rejection is all-or-none; the entire epoch is discarded if an artifact is detected in one or more channels in that epoch.
{{ :psyc410:images:Tutorial_Artifact-Detection_2.png?600 |}}
The window for saving the newly created dataset is also brought up at this point. The idea is that you will scan through the dataset, and either save it (if everything looks ''OK'') or click on ''CANCEL'' (if you want to change the parameters and try again).
**5. ** Once you have finished looking at the data, click OK in the window for saving the dataset if you are satisfied with the artifacts that were detected (it will be named "S1_EEG_elist_be_ar").
**Equivalent Script Command:**
% Artifact Detection with Moving window peak to peak threshold
% Test period [-200 798]. Voltage threshold 100uV
% Moving window width: 200 ms. Window step: 50. Channels 1:16
% Mark flags 1 and 4 (you must always mark flag 1
EEG = pop_artmwppth( EEG, 'Channel' , 1:16, 'Flag' , [1 2]. 'Threshold', 100 ...
, 'Twindow', [-200798], 'Windowsize' , 200, ' Windowstep' , 50);
% The script-based routine does not show you the data. To see the data, do this:
pop_eegplot(EEG);
% Now we will save the dataset
% Setname is S1_EEG_elist_be_ar
% Filename is S1_EEG_elist_be_ar.set
% Path is /Users/etfoo/Desktop/tutorial_script/
% Note that you will need to replace the path with the actual location in your file system
EEG.setname='S1_EEG_elist_be_ar';
EEG=pop_saveset(EEG, 'filename', 'S1_EEG_elist_be_ar.set', 'filepath', '/Users/etfoo/Desktop/tutorial_script/');
%The following command uses Matlab's Current Folder
EEG.setname='S1_EEG_elist_be_ar';
EEG=pop_saveset(EEG, 'filename', 'S1_EEG_elist_be_ar.set');
/*
ote that the scrolling EEG display window ordinarily allows you to click on an epoch that has not been marked to manually mark it or to click on an epoch that has already been marked to unmark it. However, this ability is disabled when you are looking at the initial results of an artifact detection procedure, because the goal at this moment is to determine whether the automated procedure worked correctly. Once you are satisfied and have saved the dataset, you can open it again in the scrolling EEG display window, and then you can manually reject and unreject epochs.
*/
=== Seeing a summary of the number of artifacts detected ===
If, at some later time, you want to see how many trials have been marked for rejection in a given dataset, you can select ''ERPLAB'' -> ''Summarize artifact detection'' -> ''Summarize EEG artifacts in a table''. This will print a table of the number of trials marked for rejection in each bin, along with the number of occurrences of each flag (which ordinarily corresponds to different types of artifacts). In our example, it should look like this if you print the table in the command window:
{{ :psyc410:images:Tutorial_Artifact-Detection_3.png?600 |}}
You can also get this information after averaging with ''ERPLAB'' -> ''Summarize artifact detection'' -> ''Summarize ERP artifacts in a table''.
/*
==== Rejecting multiple times and clearing flags ====
Imagine that you want to do artifact rejection twice, once on the VEOG channel with a relatively low threshold (e.g., 75 µV) and short moving window length (e.g., 200 ms) to detect blinks, and once on all the other channels with a relatively high threshold (e.g., 200 µV) and long moving window length (e.g., 1000 ms) to detect other kinds of artifacts (e.g., EMG bursts, skin potentials, etc.). You can simply run the artifact detection routine once with one set of parameters, save the dataset, and then run the artifact detection routine on this new dataset with a new set of parameters. Any artifacts marked in the dataset prior to artifact detection will remain marked when artifact rejection is performed on that dataset, and any additional artifacts will be marked in the new dataset. If you wish to unmark everything and start over, you can either clear the datasets and go back to an unmarked dataset or select ''ERPLAB'' -> ''Artifact Detection'' -> ''Clear Artifact Detection Marks on EEG'' which then displays the following figure.
{{ :psyc410:images:Tutorial_Artifact-Detection_4.png?600 |}}
To reset the artifact detection marks, make sure ''Reset Artifact Rejection Marks'', ''Reset Flags'', and ''All flags'' are selected, then click ''OK''. After you click OK, a window pops up prompting you to name the new dataset.
**Equivalent Script Command:**
% Artifact Detection, Clear Artifact Detection Marks on EEG
EEG = pop_resetrej(EEG, 1, 65535);
==== Combining EEGLAB and ERPLAB Artifact Detection ====
EEGLAB allows you to manually delete sections of the continuous EEG with artifacts from within the ''Plot'' -> ''Channel data (scroll)'' window. This deletion is permanent (although you can always go back to a previous version of the data in which the data have not been deleted). Manual deletion also causes the insertion of a //boundary// event. This type of artifact rejection is performed on the continuous EEG, so it is prior to (and independent of) ERPLAB's artifact detection.
EEGLAB also has routines for marking epochs for deletion (and you can optionally delete the rejected epochs from the EEG in addition to marking them). The most useful of these routines allows you to visually inspect the data and click on epochs that you would like to mark for deletion (''Tools'' -> ''Reject data epochs'' -> ''Reject by inspection''). If you use any of EEGLAB's routines for marking epochs for rejection, the marks will not automatically be propagated to the artifact flags in the EVENTLIST (because EEGLAB doesn't "know" anything about the EVENTLIST structure). Similarly, any manual rejection that you do by simply changing the EVENTLIST flags won't be propagated to EEGLAB's rejection marks (EEG.reject). When you average the ERPs, ERPLAB's averaging routine automatically rejects trials marked in either place, and the EVENTLIST in the ERP will contain marks for both types of rejections.
In addition, you can force the synchronization of these two sets of marks with ''ERPLAB'' -> ''Artifact Detection'' -> ''Synchronize Artifact Info in EEG and EVENTLIST''. This can also be achieved from scripts or from the command line with the pop_syncroartifacts() routine. Note: If you unreject epochs using Reject by inspection in EEGLAB, you must transfer the marks from EEG.reject to the EVENTLIST, but not vice versa.
*/
/*
==== Example 2: Step-like artifacts ====
To see how this works, let's take the dataset that you've already marked with rejections using the ''Moving window peak-to-peak threshold'' test and apply another test, the ''Step-like artifacts'' test. In this example, we will attempt to detect horizontal eye movements in the HEOG channel (channel 16).
Saccadic eye movements have a distinctive shape, because the eyes are steady at one location for a period of time, then jump to another location, stay steady for a period of time, and then jump to yet another location, so the HEOG signal is relatively flat, suddenly jumps to a new level, stays flat for a period of time, and then jumps to a new level. In many cases, the eyes are on the fixation point, jump away for a few hundred milliseconds, and then jump back to fixation. When this happens, the HEOG signal has a boxcar shape, as in the screenshot shown below.
{{ :psyc410:images:Tutorial_Artifact-Detection_5.png?600 |}}
The current data file has quite a bit of high-frequency noise that makes it difficult to see this small artifact (which was at epoch #208). Thus, the data shown in the screenshot above were first filtered with a 30-Hz low-pass filter. To get a close-up view of the artifact, the time window to display was set to 1 epoch and the number of channels to display was set to 3 (within the ''Settings'' menu within the plotting window).
Without the filter, the plot will look like the following screenshot:
{{ :psyc410:images:Tutorial_Artifact-Detection_6.png?600 |}}
The Step-like artifacts function is well suited to detecting this type of artifact (see the User's Manual for more details about this function).
**1. ** Make sure that the dataset you created with the first artifact test is selected
**2. ** Select ''ERPLAB'' -> ''Artifact detection in epoched data'' -> ''Step-like artifacts''.
* Enter the parameters as shown in the screenshot below
* Make sure that ''Flag 3'' is selected (you should have selected Flag 4 when you did the peak-to-peak detection
* You are detecting artifacts **only in Channel 16**.
* Note that the full width of the step function is set to 400 ms. This means that we are looking for a period of one voltage for >=200 ms immediately followed by a period of a different voltage for >=200 ms. This width was chosen because gaze fixation periods almost always last for at least 200 ms.
* Click ''ACCEPT''
{{ :psyc410:images:Tutorial_Artifact-Detection_7.png?600 |}}
You will see in the command window that this routine found artifacts on 12.8% of trials. If you look at the scrolling data window that pops up, you will see that some of the epochs with these artifacts also had blink artifacts that were detected with the **peak-to-peak amplitude** routine that was previously run with these data (e.g., epoch 44 indicates a rejection of the HEOG channel by drawing this channel in red, and the data from several other channels are also drawn in red from the peak-to-peak artifact detection). However, other epochs were rejected solely because of the step function in the HEOG channel (e.g., epochs 208 and 209).
Equivalent Script Command:
% Artifact Detection, Step-like artifacts
% Test period [-200 798], Voltage Threshold 15
% Moving Window Width 400, Window step 10
% Channel 16 only, Mark flags 1 and 3 (you must always mark flag 1
EEG = pop_artstep( EEG,'Channel' , 16, 'Flag', 1, 'Threshold', 15 ...
, 'Twindow' , [-200 798], 'Windowsize' , 400, 'Windowstep' , 10);
=== Looking at artifact information in the EventList ===
Information about the artifacts can also be found in the EventList. To see this, save the EventList from the current dataset in a text file by selecting ''ERPLAB'' -> ''EventList'' -> ''Export EEG EventList to Text File''. Now open the text file in Matab's text editor. You will see something like the following.
{{ :psyc410:images:Tutorial_Artifact-Detection_8.png?600 |}}
If you look at the column of artifact rejection flags (a_flags), you will see that every rejected trial has flag 1 set (the rightmost flag). Some of the events have flag 4 set from the peak-to-peak routine (e.g., item 157). Other events have flag 3 set from the step function routine (e.g., item 159), and other events have both flags 3 and 4 set (e.g., item 167), indicating that both types of artifacts were detected. This information can be useful if you want to perform behavioral analyses excluding trials with specific types of artifacts.
**Equivalent Script Command:**
% Export EEG Eventlist to Text file
% Filename is Export_EEG_EL.txt
% Path is /Users/etfoo/Desktop/tutorial_script
% Note that you will need to replace the path with the actual location in your file system
EEG = pop_exporteegeventlist(EEG, '/Users/etfoo/Desktop/tutorial_script/Export_EEG_EL.txt');
% The following command uses Matlab's Current Folder
EEG = pop_exporteegeventlist(EEG, 'Export_EEG_EL.txt');
Note that the left column in this text file shows the original item number of the event, from the original continuous dataset. The second column shows the bin epoch (bepoch) number, which is the item number after epoching. These numbers will be different when some event codes are not used as time-locking events when the data are epoched (e.g., the response event codes in the current example). If you are trying to find an event in the continuous data with ''Plot'' -> ''Channel data (scroll)'', you should use the item number (first column). If you are trying to find an event in the epoched data, you should use the bepoch number (second column).
Note for programmers: The flags are shown in a binary format in the text file (to make it easier to see the individual flag values). However, they are stored in a single variable, and Matlab ordinarily uses decimal numbers to enter and print the value of a variable. For example: If you set flags 1 and 5 in an artifact detection tool, and you print out the value of the flag variable, you will see a value of 17.
*/
What do you know?
* Why is artifact rejection important?
* Is there a "right" way to do artifact rejection?
* Will all artifact rejection techniques yield the same or similar results?
**Do not proceed until you answer "yes" to all of the above". You will not be successful in your next two lab reports without a thorough understanding of each of tonight's steps.** //Let me know if you're struggling.//
===== Creating Averaged ERPs =====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Creating-Averaged-ERPs:-Tutorial|Creating Averaged ERPs]]
^ Requirements ^ Completed? ^
| Loaded Data | ✓ |
| Creating an EventList | ✓ |
| Creating Bin-Based EEG Epochs | ✓ |
| Artifact Detection | ✓ |
| Creating Averaged ERPs | |
We are now (finally!) ready to create a set of averaged ERP waveforms.
**1. ** Make sure that the correct dataset is active, ''S1_EEG_elist_be_ar'', which has been epoched and scanned for artifacts with the Moving Window peak-to-peak threshold artifact detection function).
**Equivalent Script Command:**
% Load S1_EEG_elist_be_ar.set
EEG = pop_loadset( 'filename', 'S1_EEG_elist_be_ar.set', 'filepath', '/Users/etfoo/Desktop/tutorial_script/');
% The following command uses Matlab's Current Folder
EEG = pop_loadset('filename', 'S1_EEG_elist_be_ar.set');
**2. ** select ''ERPLAB'' -> ''Compute Averaged ERP''. This will bring up the very simple window shown below.
{{ :psyc410:images:tutorial_creating-averaged-erps_2.png?600 |}}
You will normally average the data in the current dataset, which is listed by default in the ''Dataset(s)'' field. You also can specify multiple datasets and average across them as if all the epochs were stored in a single dataset. In this tutorial, we will just average the epochs from a single dataset
**3. ** Click ''RUN''
Normally you will want to exclude epochs marked as containing artifacts (marked with artifact flag 1 in the EventList), which can be achieved by selecting ''Exclude epochs marked during artifact rejection''. If you want to include all epochs (ignoring the artifact flags), you can instead select ''Include ALL epochs''. It is also possible to include only the epochs that contain artifacts, excluding epochs without artifacts, by selecting ''Include ONLY epochs marked during artifact detection''. (This is uncommon, but you might do this to see the effects that the artifacts have on the data.)
**Equivalent Script Command:**
% Compute Averaged ERP
% To average the data from dataset 5, whether or not it is selected, use the following:
ERP = pop_averager( ALLEEG , 'Criterion', 1, 'DSindex', 5, 'Stdev', 'on');
% To average the data from datasets 3-5, use the following:
ERP = pop_averager( ALLEEG , 'Criterion', 1, 'DSindex', 3:5, 'Stdev', 'on');
% In all of these examples, the 'Criterion' argument specifies how artifacts should be treated:
% 1 – Exclude trials with artifacts (as in these examples)
% 0 – Include all trials (ignore artifact flags)
% 2 – Include ONLY trials with artifacts
The averaging routine will print some useful information in the Matlab command window, as shown in the screenshot below. Specifically, it will show the percentage of trials that were excluded because of artifacts and because of invalid trials (e.g., epochs with boundary events within them; invalid trials should be rare). This information is provided both collapsed across bins and separately for each bin.
{{ :psyc410:images:tutorial_creating-averaged-erps_3.png?600 |}}
When the averaging routine is finished, it will display the window shown below, which allows you to name and save the ERPset that was created. This window is shown every time an ERPLAB function modifies or creates an ERPset. If one or more ERPsets were already loaded, you would have the option of overwriting the previously active ERPset or creating a new ERPset (you will usually want to create a new one – ERPsets are usually much smaller than datasets, and you will not usually run out of RAM because of ERPsets). In this case, however, no other ERPsets are present, so you will be creating a new ERPset.
**4. ** You should name the ERPset "S1_ERPs".
* This is the name that will be shown in the ERPsets menu.
* You will usually want to save the results of averaging in a file on disk, so select the ''Save ERP'' as button and give the file the same name as the ERPset name. You can do this easily by clicking the ''same as erpname'' button.
* The file will be saved in Matlab's current directory unless you either specify an alternative path or use the Browse button.
* You can click the ''OK'' button once you have set up the window as shown in the screenshot below.
{{ :psyc410:images:tutorial_creating-averaged-erps_4.png?600 |}}
You can now see the newly created ERPset in the ''ERPsets'' menu, as shown in the screenshot below.
{{ :psyc410:images:tutorial_creating-averaged-erps_5.png?600 |}}
**Equivalent Script Command:**
% Setname is S1_ERPs
% Filename is S1_ERPs.erp
% Path is /Users/etfoo/Desktop/tutorial_script/S1_ERPs.erp
% Note that you will need to replace the path with the actual location in your file system
ERP = pop_savemyerp( ERP, 'erpname', 'S1_ERPs.set','filename', 'S1_ERPs.erp' ...
, 'pathname', '/Users/etfoo/Desktop/tutorial_script/');
% The following command uses Matlab's Current Folder
ERP = pop_savemyerp( ERP, 'erpname', 'S1_ERPs.set', 'filename', 'S1_ERPs.erp');
===== Plotting Averaged ERP Data Waveforms =====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Plotting-Averaged-ERP-Waveforms:-Tutorial|Plotting Averaged ERP Waveforms]]
^ Requirements ^ Completed? ^
| Loaded Data | ✓ |
| Creating an EventList | ✓ |
| Creating Bin-Based EEG Epochs | ✓ |
| Artifact Detection | ✓ |
| Creating Averaged ERPs | ✓ |
Now that you have created an ERPset, you can look at its contents by plotting it.
**1. ** Select ''ERPLAB'' -> ''Plot ERP'' -> ''Plot ERP Waveforms'', which brings up the window shown in the next screenshot.
* The top half of the window allows you to specify what information to plot (bins, channels, etc.)
* the bottom half allows you to control the details of the plotting (vertical scale, line width, font size, etc.).
* The window will remember the settings from the last time you used it, but you can revert to the default settings by clicking the ''RESET VALUES'' button.
{{ :psyc410:images:tutorial_plotting-averaged-erp-waveforms_1.png?600 |}}
**2. ** Click the ''PLOT'' button with the default values, and you should see the following window pop up:
{{ :psyc410:images:tutorial_plotting-averaged-erp-waveforms_2.png?600 |}}
You can save the waveforms in a PDF file*, import them into a graphics program such as Adobe Illustrator, and then edit them. We recommend that you maximize the figure window before clicking the PDF button.
* by clicking the PDF button (i.e. toolbar - PDF button) in the upper toolbar of the resulting ERP plot
Alternatively, you can export the waveforms as text files using the ''ERPLAB'' -> ''Export and Import ERP'' -> ''Export ERP to Text'' routines and then read them into a program such as Excel or PowerPoint for plotting.
**Equivalent Script Command:**
% Plotting Averaged ERP Waveform
% Bins to plot [1,2], Channels to plot [1:16],
% Pre Baseline Correction, Rows 4, Columns 4, Channels 10, Legends 10
% Line width 1, Time range [-200 798],
pop_ploterps( ERP, [ 1, 2],1:16 , 'AutoYlim', 'on', 'Axsize', [ 0.05 0.08], 'BinNum', 'on' ...
, 'Blc', 'pre', 'Box', [ 4 4], 'ChLabel', 'on', 'FontSizeChan',10, 'FontSizeLeg',10 ...
, 'LegPos', 'bottom', 'Linespec', {'k-' , 'r-' }, 'LineWidth',1, 'Maximize', 'on' ...
, 'Position', [ 102.833 9.375 108.667 35.125], 'Style', 'Matlab' ...
, 'xscale', [ -200.0 798.0 -100:170:750], 'YDir', 'normal', 'yscale', [ -10.0 10.0 -10:5:10] );
% Note that an ellipsis (...) can be used to break a long function call across multiple lines
pop_ploterps( ERP, [ 1, 2],1:16);
=== The toolbar on the figure ===
Note that in the plotting window, ERPLAB provides a custom toolbar that provides a set of buttons to ERPLAB functions. Play around with it and you should be able to figure out how it works.
{{ :psyc410:images:tutorial_plotting-averaged-erp-waveforms_3.png?600 |}}
Perhaps the most useful tool is the **Data cursor** (the icon with the small plus mark), which allows you to click on the waveform and see the X and Y values (time and voltage) at that point on the waveform.
If you click on one of the panels (e.g., the panel for the Cz electrode site), a new window will open showing an expanded version of that panel, as shown in the screenshot below. (NOTE: this won't work if the Data cursor button is depressed)
{{ :psyc410:images:tutorial_plotting-averaged-erp-waveforms_4.png?600 |}}
=== Other plotting examples ===
There are many things you can do with the Plotting Waveform GUI. For example, you could plot a single column with multiple channels. For example, set ''Channels to plot'' to ''1:4'', set ''Row(s)'' to ''4'', and set ''Column(s)'' to ''1''. You will see something like this:
{{ :psyc410:images:tutorial_plotting-averaged-erp-waveforms_5.png?600 |}}
You should take some time here (or come back to it later) and learn how to make attractive plots. This will serve you well over the next couple of weeks.
(//feel free to ask me for tips//)
===== Filtering EEG and ERPs =====
This section has been copied and modified from the ERPlab tutorial [[https://github.com/lucklab/erplab/wiki/Filtering-EEG-and-ERPs:-Tutorial|Filtering EEG and ERPs]]
ERPLAB contains a set of filters that can be applied to continuous EEG, to segmented EEG, and to averaged ERPs. Separate routines are used for filtering EEG (''ERPLAB'' -> ''Filter & Frequency Tools'' -> ''Filters for EEG data'') and for filtering ERPs (''ERPLAB'' -> ''Filter & Frequency Tools'' -> ''Filters for ERP data''). The routines are nearly identical, except for a few options. We will start by discussing the filtering of averaged ERPs.
==== Filtering ERP ===
**1. ** Make sure that "S1_ERPs" is selected in the ''ERPsets'' menu, and then select ''ERPLAB'' -> ''Filter & Frequency Tools'' -> ''Filters for ERP data''.
* You will see a window similar to the screenshot below. This window allows you to set various properties of the filter.
* First, you can determine whether to apply a low-pass filter (filtering out high frequencies) and/or a high-pass filter (filtering out low frequencies).
* For each of these, you can select the 50% amplitude cutoff point by typing a number in the corresponding text field or by adjusting the sliders.
* You can also adjust the slope of the filter's roll-off in the ''Roll-off & filter order'' panel in units of decibels per octave (''dB/oct'') or in units decibels per decade (''dB/dec'') or in terms of the filter's order (if you change one, the others will automatically change).
You can see the frequency response function of the resulting filter (the extent to which each frequency is passed by the filter) in the graph at the top of the window (assuming that the ''Plot panel'' is set to ''Frequency response''). Try playing around with the various filter parameters to see how it changes the frequency response function.
Three general classes of filters have been implemented. First, ''IIR Butterworth'' is a digital implementation of the classic ''Butterworth'' filter. The output of this filter feeds back into its input, making it an infinite impulse response filter. It filters the data in both directions, avoiding any phase shift. Second, FIR is a finite impulse response filter that uses a sinc impulse response function. This kind of filter can be very efficient but can produce artificial oscillations in the filtered data under some conditions. We will eventually implement Gaussian impulse response functions but have not done so yet. However, the sinc filter approximates a Gaussian when a relatively low filter order is used. The third option is ''Parks McClellan Notch'', which provides a notch filter (which attenuates one narrow range of frequencies and passes everything else).
Filters can dramatically distort your data, creating artificial peaks and oscillations (see Chapter 5 in //An Introduction to the Event-Related Potential Technique//). To avoid these distortions, we recommend that you choose a high-pass cutoff of 0.1 Hz or lower and a low-pass cutoff of 20 Hz or higher unless you really know what you're doing. We also recommend a roll-off slope of 12 dB/octave. For an example of how severe filtering can lead to incorrect conclusions, see //Yeung et al., 2007, Psychophysiology, 44, 39-49//.
{{ :psyc410:images:Tutorial_Filtering-EEG-and-ERPs_1.png?600 | }}
**2. ** As an example, select ''ERPLAB'' -> ''Filter & Frequency Tools'' -> ''Filters for ERP data'' and set up the filter as shown in the screenshot above
* no high-pass filter
* a low-pass half-amplitude cutoff at 30 Hz
* a roll-of of 12 dB/octave
* a Butterworth filter type
* all 16 channels being filtered.
**3. ** Click ''APPLY''.
After the filtered data have been created, the standard window for saving new ERPsets will appear, and you should name the new ERPset "S1_ERPs_30Hz" (it's a good idea to save the ERPset to disk, because we will need this file for another example later). This will now be the active ERPset. If you plot it with ''ERPLAB'' -> ''Plot ERP Waveforms'', the result will look like the following screenshots (you should also plot the unfiltered data for comparison).
{{ :psyc410:images:Tutorial_Filtering-EEG-and-ERPs_2.png?600 | }}
**Equivalent Script Command:**
%Basic Filtering for ERP
%Channels [1:16], High pass 0, Low pass 30, Order 2, IIR Butterworth
ERP = pop_filterp( ERP,1:16 , 'Cutoff',30, 'Design', 'butter', 'Filter', 'lowpass', 'Order',2 );
%Setname is S1_ERPs_30Hz.set
%Filename is S1_ERPs_30Hz.erp
%Path is /Users/etfoo/Desktop/tutorial_script/S1_ERPs_30Hz.erp
ERP = pop_savemyerp(ERP,
'erpname',
'S1_ERPs_30Hz.set',
'filename',
'S1_ERPs_30Hz.erp',
'pathname',
'/Users/etfoo/Desktop/tutorial_script/',
'warning',
'on');
%The following command uses Matlab's Current Folder pop_savemyerp(ERP, 'erpname', 'S1_ERPs_30Hz.set', 'filename', ' S1_ERPs_30Hz.erp')
* Did you compare what your ERPs looked like before and after filtering?
* Did you try different filters to see what effect they have?
==== Filtering EEG ===
Now let's try filtering continuous EEG data.
**1. ** Make "S1_Chan" the active Dataset (loading it with ''File'' -> ''Load existing dataset'' if necessary). Select ''ERPLAB'' -> ''Filter & Frequency Tools'' -> ''Filters for EEG data'' and set the parameters as shown in the screenshot below.
* high-pass filter with a cutoff at 0.1 Hz
* low-pass filter with a cutoff at 30 Hz.
* You should check the boxes for applying the filter to segments defined by boundary events (which you should always check unless you really know what you're doing) and for removing the mean value (which you should always do with DC recordings and which won't hurt for non-DC recordings). The ERPLAB User's Manual provides more details.
{{ :psyc410:images:Tutorial_Filtering-EEG-and-ERPs_3.png?600 | }}
**2. ** Once you've set the parameters, click ''APPLY''. The filtering will take a little while.
**3. ** Once it prints Done in the Matlab command window, use ''Plot'' -> ''Channel data (scroll)'' to see the filtered data, which should look like the screenshot below.
{{ :psyc410:images:Tutorial_Filtering-EEG-and-ERPs_4.png?600 | }}
In most cases, high-pass filters should be applied to the continuous EEG, not the epoched EEG or averaged ERPs. The reason is that, with typical cutoff values, a long period of continuous data is needed for these filters to work properly. Low-pass filters can be applied at any time, because they do not need a very long time period with typical settings. In most cases, however, it is best to apply low-pass filtering after averaging. Otherwise, you will need to back up to the EEG and repeat several steps if you later decide to change the filter settings. However, low-pass filtering can sometimes improve artifact detection, in which case you can apply the low-pass filter to either the continuous or epoched EEG prior to artifact detection.
**Equivalent Script Command:**
%Load S1_Chan from the current folder
EEG = pop_loadset( 'filename', 'S1_Chan.set');
%Basic Filtering for EEG with High pass
%Channels 1:16, High-Pass 0.1, Low-Pass 30, Order 2,
%IIR Butterworth, Apply filter to segments defined by boundary events
%Boundary event code 'boundary'
EEG = pop_basicfilter( EEG, 1:16 , 'Boundary', 'boundary', 'Cutoff', [ 0.1 30], ...
'Design', 'butter', 'Filter', 'bandpass', 'Order', 2, 'RemoveDC', 'on' );
===== Plotting Averaged ERP Data Scalp Maps =====
Another way we can look at our results is by plotting scalp voltage maps (aka topgographic or topo maps). These maps show the responses across the entire scalp at a single point in time or the average over a window of time. As with the ERP waveforms, ERPLAB makes it easy to [[https://github.com/lucklab/erplab/wiki/Topographic-Mapping|plot these scalp maps]].
**1. ** Select ''ERPLAB'' -> ''Plot ERP'' -> ''Plot ERP scalp maps'', which brings up the window shown in the next screenshot.
* The top half of the window allows you to specify what information to plot (bins, channels, etc.)
* the bottom half allows you to control the details of the plotting (vertical scale, line width, font size, etc.).
* The window will remember the settings from the last time you used it, but you can revert to the default settings by clicking the ''RESET VALUES'' button.
{{ :psyc410:images:Manual_Topographic-Mapping_1.png?800 |}}
To plot a set of topographic maps, you start by selecting what kinds of values to plot. The options are:
* **Instantaneous amplitude** - The amplitude at a single time point (e.g., 300 ms)
* **Mean amplitude between two fixed latencies** - The mean voltage in a time period (e.g., 300-400 ms)
* **Instantaneous amplitude Laplacian** - Surface Laplacian plot of instantaneous amplitude
* **Mean amplitude Laplacian** - Surface Laplacian plot of mean amplitude
* **Root mean square value** - This is the RMS voltage over a specified time range
For instantaneous amplitude, you provide a set of one or more latencies in the Latencies to plot text box (e.g., "100 150 200 250 300" or equivalently "100:50:300"). For mean or RMS amplitude, you provide one or more sets of time periods. For example, you would specify 300 450 to plot the scalp distribution of the mean voltage between 300 and 450 ms. You can also specify multiple time periods, separated by semicolons (e.g., "200 300 ; 300 400; 400 500" to plot maps of mean amplitude from 200-300, 300-400, and 400-500).
There are several options for determining the scale of the maps. If you select Max-Min, the routine automatically chooses a scale for each bin on the basis of the minimum and maximum voltages found in that bin (e.g., the chosen scale might go from -4 µV to +9 µV). If you select Abs Max, the routine finds the minimum and maximum values, and creates a symmetrical scale depending on which has a greater absolute value (e.g., the chosen scale might go from -9 µV to +9 µV). For these two options, each bin is scaled separately. A third option is Custom, which allows you to specify the minimum and maximum values (e.g., you might put -5 +5 in the text box). In this case, the scale is the same for each bin. There are a variety of additional plotting options (e.g., turning on or off electrode markers) that are accessed with the Options button.
**2. ** If you go back and look at the waveforms you plotted, you'll notice that the P3 was largest roughly between 300 and 600 ms post-stimulus. So ...
* set **Bin(s) to plot** to ''1 2''
* Here we saying to plot topo maps of the frequent bin and the rare bin
* set **Value to plot** to ''mean amplitude between two fixed latencies''
* set **Latency(ies) to plot in ms** to ''300 600''
* set **Color bar scale** to ''Custom'' ''-6 6''
* I've chosen these values because I know what the results look like. Obviously, in reality that wouldn't be the case and you'd have to explore which scales best display the results.
* click ''PLOT'' and you should get something like the figure below
{{ :psyc410:images:topomap_1.png?400 | }}
We can clearly see the strong positive voltage over the centroparietal scalp when the participant viewed the rare stimuli (bottom row) compared to when they viewed the frequent stimuli (top row).
You can also choose between 2D maps (which always use a top viewpoint) and 3D maps (which allow you to specify the viewpoint). If you want to try it ...
* set **Bin(s) to plot** to ''1 2''
* set **Value to plot** to ''mean amplitude between two fixed latencies''
* set **Latency(ies) to plot in ms** to ''300 600''
* set **Color bar scale** to ''Custom'' ''-6 6''
* change **Map type** to ''3D''
* click on ''spline''
* click on ''Create new spline file and save it as''
* In this text box just enter ''spline'' (or whatever, really)
* click ''OK''
* click ''PLOT'' and you should get something like the figure below
{{ :psyc410:images:topomap_2.png?400 | }}
Cool, right?
Click the icon that looks like a cube wrapped in a counter-clockwise arrow. Now you can click on your 3D head and rotate it around.
You should take some time here (or come back to it later) and learn how to make attractive plots. This will serve you well over the next couple of weeks.