Home/Download Tutorial Revision History Contact/Questions Appendix Other EEG Analysis Software Packages

The partial appendix contains descriptions of key data structures and functions used by the Mass Univariate ERP Toolbox.

DATA STRUCTURES

EEG variables

EEG - EEGLAB data structure for holding a single subject's single trial EEG data and associated experimental event information. For full details see http://sccn.ucsd.edu/wiki/A05:_Data_Structures. Here we only cover the fields of the EEG variable modified or added by the Mass Univariate ERP toolbox. These fields are modified or added by using the function bin_info2EEG.m. Note, if you use ERPLAB and the function erplab2GND.m to create GND variables, you will not use the function bin_info2EEG.m and the Mass Univariate ERP Toolbox will not modify any EEG variables.

EEG fields modified by the Mass Univariate ERP toolbox

event:<-this struct array contains an entry for every "event" (e.g., stimulus onset, button press) in the experiment. To make the EEG variable usable by the Mass Univariate ERP Toolbox, for all events that fall into a particular bin (say Bin 1), a bin event is added to EEG.event with a bin type (e.g., EEG.event(100).type='bin1') with the same latency, urevent, and duration as the source event.
epoch:<-this struct array contains an entry for every epoch of data. The ith entry of EEG.epoch lists all the events that occurred in the ith epoch. As with EEG.event, for every event in that epoch that falls into a particular bin (say Bin 1), a copy of that event is added with a bin type (e.g., EEG.epoch(1).eventtype{5}='bin1').

EEG fields added by the Mass Univariate ERP toolbox

bindesc:<-this cell array contains a "bin descriptor" for each bin in the bin list file. The bin descriptor is simply a string that describes the type of trial that falls into that bin (e.g., 'Targets').

GND variables

GND - Data structure repository for all the ERP data and results of within-subject analyses. Included are the grand average time domain waveforms (average across subjects) at all electrodes, the individual subject average waveforms comprising the grand average, a log of the statistical tests conducted on the data and related bookkeeping information: numbers of subjects and trials, bin labels, timepoints in millseconds for the waveform data, electrode locations and more.

Here's what the various fields of a GND variable store:

exp_desc:<-the name of the experiment
filename:<-the filename of the GND variable
filepath:<-the filepath of the GND variable
saved: <-whether or not the GND variable has been saved since it was last modified
grands: <-grand average ERPs (channel x time point x bin) in microvolts
grands_stder: <-standard error of the grand average ERPs (channel x time point x bin) in microvolts
grands_t: <-t-scores of the grand average ERPs (channel x time point x bin), which is simply the grand average divided by the standard error
sub_ct: <-the number of subjects contributing to the grand average ERP for each bin
chanlocs: <-electrode coordinates in EEGLAB format
bin_info: <-struct array containing the text definition of each bin and it's "condition code." Condition codes are specific to Kutaslab data and can be ignored by non-Kutaslab users.
condesc: <-text descriptions of each condition code. Again, condition codes are specific to Kutaslab data and can be ignored by non-Kutaslab users.
time_pts: <-the peri-event time that each ERP time point corresponds to (in milliseconds)
bsln_wind: <-the time window used to baseline the ERPs (in milliseconds)
odelay: <-A field specific to Kutaslab data that can be ignored by non-Kutaslab users.
srate: <-Data sampling rate (in Hz)
indiv_fnames:<-The filenames of the set files used to produce the GND variable.
indiv_subnames:<-The codenames of each subject
indiv_traits: <-A field where you could store traits of individual subjects (e.g., age, working memory span)
indiv_bin_ct: <-The number of trials each participant contributed to each bin.
indiv_bin_raw_ct: <-A field specific to Kutaslab data that can be ignored by non-Kutaslab users.
indiv_erps: <-The ERPs from each individual subject (channel x time point x bin x subject) in microvolts
indiv_art_ics: <-The numeric indices of independent components removed from each set file before using them to compute ERPs
cals: <-A field specific to Kutaslab data that can be ignored by non-Kutaslab users.
history: <-A record of commands applied to the GND variable
t_tests: <-The results of mass univariate t-test analyses applied to this GND variable

GRP variables

GRP - A data structure derived from two or more GND structures used for between-group analyses.

Here's what the various fields of a GRP variable store:

exp_desc:<-the name of the experiment (this is taken from the source GND variables)
filename:<-the filename of the GRP variable
filepath: <-the filepath of the GRP variable
saved: <-whether or not the GRP variable has been saved since it was last modified
group_desc: <-strings indicating the name of each group in the GRP variable
GND_fnames:<-the filenames and paths of the source GND variables used to make the GRP variable
grands: <-grand average ERPs (channel x time point x bin) in microvolts
grands_stder: <-standard error of the grand average ERPs (channel x time point x bin) in microvolts
grands_t: <-t-scores of the grand average ERPs (channel x time point x bin), which is simply the grand average divided by the standard error
chanlocs: <-electrode coordinates in EEGLAB format
bin_info: <-struct array containing the text definition of each bin, the number of participants from each group contributing to each bin, how the bin was produced from the two groups, and it's "condition code." Condition codes are specific to Kutaslab data and can be ignored by non-Kutaslab users. GRP.bin_info(#).op indicates if the bin contains a difference wave ('A-B') or the mean of the ERPs from the two groups ('A+B'). The rest of the fields indicate which group corresponds to Group A and Group B and which bins from each group were used.
condesc: <-text descriptions of each condition code. Again, condition codes are specific to Kutaslab data and can be ignored by non-Kutaslab users.
time_pts: <-the peri-event time that each ERP time point corresponds to (in milliseconds)
bsln_wind: <-the time window used to baseline the ERPs (in milliseconds)
odelay: <-A field specific to Kutaslab data that can be ignored by non-Kutaslab users
srate: <-Data sampling rate (in Hz)
indiv_fnames: <-The filenames of the set files used to produce the source GND variables
indiv_subnames: <-The codenames of each subject in each of the two groups
indiv_traits: <-A field where you could store traits of individual subjects (e.g., age, working memory span)
indiv_bin_ct: <-The number of trials each participant contributed to each bin of the GRP variabl. This field is cell array with one entry for each group. Each group's entry is a 2D array (# of participants x # of GRP bins).
indiv_bin_raw_ct: <-A field specific to Kutaslab data that can be ignored by non-Kutaslab users.
indiv_art_ics: <-The numeric indices of independent components removed from each set file before using them to compute ERPs
cals: <-A field specific to Kutaslab data that can be ignored by non-Kutaslab users
history: <-A record of commands applied to the GRP variable
t_tests: <-The results of mass univariate t-test analyses applied to this GRP variable

USER INTERFACE & DATA VISUALIZATION FUNCTIONS

gui_erp

Opens a GUI for visualzing ERP butterfly plots and topographies. ERP t-scores, standard error and global field power (Lehmann & Skrandies, 1980) can also be visualized. Hold mouse cursor over GUI controls for an explanation of what they do. Click on waveform axes to visualize the scalp topography at that point in time. Click on electrodes in scalp topography to see electrode name. Note, you can open more than one "gui_erp" at a time in different windows, but you cannot animate more than one gui_erp window at a time.

plot_wave

Plots the ERPs from one or more bins in a GND or GRP variable in uV or t-scores. Each channel is visualized on its own axis.

sig_raster

Plots 2D (electrode x time) raster diagram of samples that show significant effects according to t-tests. Significant positive effects are represented with white squares (red if color is requested). Significant negative effects are represented with black squares (blue if color is requested). Called on GND or GRP variables. Note, some image viewers (e.g., Apple's Preview) may have trouble viewing postscript raster images since some downsample the image to make the file smaller, which blurs the lines. gv and Adobe Illustrator should be able to view the files just fine. If viewing the raster as a postscript file is producing problems, you can try saving the figure in jpg format.

sig_topo

Plots scalp topographies of ERPs/ERP effects that have been tested for significance as a family of tests. Only works for ERPs/ERP effects derived from averaging time points within a mean time window. Called on GND or GRP variables.

sig_wave

Creates a butterfly plot of ERPs illustrating the results of a mass univariate t-test. Only works for mass univariate tests applied to every single time point within one or more time windows (i.e., it doesn't work when you apply t-tests to the average voltage within one or more time windows). Called on GND or GRP variables.

topoplotMK

Plots a topographic map of a scalp data field in a 2-D circular view (looking down at the top of the head) using interpolation on a fine cartesian grid. Can also show specified channnel location(s). This is a slightly modified version of the EEGLAB function topoplot.m. A few optional inputs have been added.

MASS UNIVARIATE TOOLBOX DATA STRUCTURE UTILITIES

baselineGND

Baseline the ERPs in a GND struct variable by removing the mean amplitude within a specified time window.

bin_dif

Computes the difference waves from two bins and stores the difference as a new bin in a GND variable.

bin_info2EEG

Adds "bin" information to an EEGLAB EEG variable based on a "bin list file," a text file that indicates which types of events belong to which bins. See the help comments for the function read_bin_list_file.m for information on how to create a bin list file. Note, the EEG variable needs to contain epoched data.

bin_opGRP

Computes the difference waves from two bins or the mean of two bins of a GRP variable and stores the resultant ERPs as a new bin in the GRP variable.

decimateGND

Downsamples a set of ERPs to a lower sampling rate. Useful for reducing the number of dependent variables and conserving memory.

erplab2GND

Creates a GND struct variable from a set of ERPLAB *.erp files

GNDs2GRP

Creates a GRP variable from a set of GND variables. A GRP variable is necessary for doing between-subjects analyses. Note, all the GND files need to have samples at the same points in time, the same baseline window, and compatible sets of electrodes.

headinfo

Displays a summary of channel, bin and t-test information stored in a GND or GRP variable.

read_bin_list_file

Extracts "bin" information from a text file called a "bin list file." The bin list file (blf) indicates which types of events belong to which bins. Each line of the blf needs to start with a number followed by a closed parenthesis, which indicates the bin number. Next comes a string, number, or a series of numbers indicting the "type" of events that fall in that bin.

remove_artifact_ics

Removes the independent components (ICs) of an EEGLAB "EEG" variable that have been labeled as an artifact in EEG.ic_labels or EEG.reject.gcompreject. The artifacts are removed from EEG.data and EEG.data is optionally baselined. Artifact status of labels in EEG.ic_labels is based on is_art.m. Note, that EEG.ic_labels is a field specific to Kutaslab data. For non Kutaslab users, artifact ICs will be denoted as such in EEG.reject.gcompreject.

rm_bins

Removes bin from a GND or GRP variable.

rm_ttest

Removes sets of t-test results from a GND or GRP variable.

save_erps

Saves a GND or GRP variable to disk using its current filename or a newly specified filename.

save_matmk

Same functionality as save_erps.m but also works for mass univariate spectral analyses, which are not currently supported by the public version of the Mass Univariate ERP Toolbox.

sbjct_info2set

Imports information about a subject into the epochs of an EEGLAB .set file from a text file. The new information (e.g., age, sex) is added to the EEG.event and EEG.epoch fields of the EEG struct variable. Currently the Mass Univariate ERP Toolbox does not support analyses based on individual subject differences, but we hope to add such functionality in the future.

sets2GND

Creates a GND struct variable from a set of EEGLAB *.set files

MASS UNIVARIATE TOOLBOX DATA ANALYSES

clustGND

Tests the null hypothesis that the grand average voltage of a bin is mu or that the grand average within-subject difference between two bins is mu using a permutation test based on the "cluster mass" statistic. This function requires individual subject ERPs to be stored in a "GND" structure and outputs the test results in a number of graphical and text formats. For analogous between-subject comparisons use the function clustGRP.m.

clustGRP

Tests the null hypothesis that the grand average voltage of a between-subject difference wave or ERP averaged across two groups is mu (usually 0) using a permutation test based on the "cluster mass" statistic. This function requires individual subject ERPs to be stored in a GRP structure and outputs the test results in a number of graphical and text formats. For analogous within-subject comparisons use the function clustGND.m. Note, when applied to a bin that is the mean ERP across two groups (i.e., NOT a difference wave), a one-sample test is executed.

fast_t1

Computes a 2D matrix of one sample/repeated measures t-tests relatively quickly.

fast_t2

Computes a 2D matrix of independent sample t-tests relatively quickly.

fdr_bh

Executes the Benjamini & Hochberg (1995) and Benjamini & Yekutieli (2001) procedure for controlling the false discovery rate (FDR) of a family of hypothesis tests. FDR is the expected proportion of rejected null hypotheses that are false discoveries.

fdr_bky

Executes the "two-stage" Benjamini, Krieger, & Yekutieli (2006) procedure for controlling the false discovery rate (FDR) of a family of hypothesis tests.

mxt_perm1

One sample permutation test based on a t-statistic and null hypothesis of a mean of zero. Can handle multiple electrodes and time points.

mxt_perm2

Two sample permutation test based on a t-statistic and null hypothesis of a mean difference of zero. For one-tailed tests, the null distribution is derived from the most extreme t-score of all permutations. For two-tailed tests, the null distribution is derived from the maximum absolute t-score of all permutations. Can handle multiple electrodes and time points.

spatial_neighbors

Creates a 2D binary matrix that indicates whether or not two electrodes are considered spatial neighbors. Used by cluster-based permutation tests.

tfdrGND

Tests the null hypothesis that the grand average voltage of a bin is mu or that the grand average within-subject difference between two bins is mu using one of several possible false discovery rate (FDR) procedures to control for mulitple comparisons (note, mu is assumed to be 0 by default). This function requires individual subject ERPs to be stored in a "GND" structure and outputs the test results in a number of graphical and text formats. For analogous between-subject comparisons use the function tfdrGRP.m.

tfdrGRP

Tests the null hypothesis that the grand average voltage of a between-subject difference wave or ERP averaged across two groups is mu (usually 0) using t-tests with false discovery rate (FDR) control to correct for multiple comparisons. This function requires individual subject ERPs to be stored in a GRP structure and outputs the test results in a number of graphical and text formats. For analogous within-subject comparisons use the function tfdrGND.m. Note, when applied to a bin that is the mean ERP across two groups (i.e., NOT a difference wave), a one-sample test is executed.

tmaxGND

Tests the null hypothesis that the grand average voltage of a bin is mu or that the grand average within-subject difference between two bins is mu using a tmax permutation test based on the conventional one-sample/repeated-measures t-statistic. Note, mu is usually 0.

tmaxGRP

Tests the null hypothesis that the grand average voltage of a between-subject difference wave or ERP averaged across two groups is mu (usually 0) using a permutation test based on the tmax statistic (e.g., Hemmelmann et al., 2004). This function requires individual subject ERPs to be stored in a GRP structure and outputs the test results in a number of graphical and text formats. For analogous within-subject comparisons use the function tmaxGND.m. Note, when applied to a bin that is the mean ERP across two groups (i.e., NOT a difference wave), a one-sample test is executed based on the conventional one-sample t-statistic.

Mass Univariate ERP Toolbox: Appendix