Psychophysiology Tool Box (PTB)
for Matlab

  Edward Bernat, Ph.D.
Department of Psychology
University of Maryland
Quick Start

Download toolbox and example archives and unpack into one directory.  They will unpack into separate subdirectories. 

components directory - Primary analysis scripts are run from the components directory.
  1. Modify startup.m to point to path of unpacked Psychyphysiology Toolbox.
  2. Start matlab from the components directory
  3. Look in scripts/*run*.m files (or run them) to see which scripts to start with.  Inspecting and running these scripts is the primary method for becoming familliar with operation. 
examples_datasets directory - Data reduction and aggregation examples.
Archives
   
Windows users NOTE -- many windows unzipping programs do not correctly handle symbolic links for.  Some archives (particularly the toolbox itself) use some symbolic links.  Compatible tools are unzip, gzip (http://gnuwin32.sourceforge.net), or a more full implementation of the GNU utilities such as cygwin (http://www.cygwin.org). 

Psychophysiology Toolbox - Main Toolbox Archive
 
Download Psychophysiology Toolbox (.tgz with symbolic links) 

Examples: Directory Structure, Scripts, Output, and Datasets     Examples Archive (download archive(s) and unpack into one directory)
License
Toolbox Operation

Requirements/Dependencies

Operating System: developed on linux, tested under Windows 2000/XP

Matlab: version 6 or higher (tested through 2014b)

Toolbox dependencies:
Script oriented - A primary aim has been to facilitate aggregate operations across large psychophysiological datasets, generally spanning many files, by more advanced users.  For this reason, development of these related toolboxes has been oriented to execution through user-defined scripts rather than developing a GUI.  To facilitate getting going, an extensive set of example scripts, along with example datasets, are included.

Data Structure (EEGLAB or PTB native)

EEGLAB: The PTB has been extended to run using EEGLAB files.  Cached data files resulting from the analyses will still be in the PTB native format (matlab, but different structure to the file).

PTB Native Format: Data and index variables are stored together in a structured variable: cnt (continuous), erp (epoched), components (derived measures from erp variable).  The toolbox operates as a flat-file database (a 'univariate' data setup).  A main 2-d data matrix (trials by waveforms) is indexed by vectors the same length as trials.  Several such index variables are integral to the data structure, such as the electrode of each waveform, sweep number, trigger, etc..  A structured sub-variable 'stim' is designed to hold an unlimited number of additional index variables to allow additional indexing of the waveforms in all processing functions.  Further details of this structure are available in the documentation directories. 

Time-Frequency Distributions  (TFDs)

The default TFD method is Cohen's class RID, using the Time-Frequency Toolbox.  This can be changed via the SETvars.TFDparams variable in the Components toolbox, generally set in the ~datasetname_loadvars.m script (see examle archives for examples using each of the above toolboxes).  If no SETvars.TFDparams is defined, the default TFD method will be used will be used. 

External code is utilized for generating all TFDs in the toolbox.  This is done because TFD methods vary widely, and PCA can be applied to surfaces created with nearly any transform method.  The goal here is to offer a generalized environment for analyzing TFDs that can be used with any researcher's favorite TFD, as well as the TFDs the have been used and tested extensively already. 

The interface for all TFD code is in the function generate_TFD.m, contained in the data_processing subdirectory.   External TFD methods can be added by creating a script with a name conforming to generate_TFDs_~methodmane.  Then in the ~datasetname_loadvars.m file, the variable SETvars.TFDparams.method must be set to ~methodname.  Any parameters needed for the method can be put as additional variables in the TFDparms structure (using any desired names).  Please see generate_TFDs for variables available to the external script at runtime.   Currently, the TFD must produce uniform frequency TFD (i.e. not log, scale, or other nonuniform axes as are common with wavelets).  The included script for using the Matlab Wavelet Toolbox (generate_TFDs_matlab_wavelet_toolbox.m) is to interpolate the wavelet surface to uniform frequency before passing the TFDs back to the toolbox. 

The majority of development and testing has been done with the Time-Frequency Toolbox (TFTB).  Support for Jeff Oneil's DiscreteTFD (DTFD) Toolbox has also added to have a GPL Cohen's class RID implementation.  Also included is Finally, for wavelets, Matlab's support for Matlab's Wavelet Toolbox has been included, for continuous wavelets (cwt).  Support for discrete wavelets useing Matlab's Wavelet Toolbox is being developed.  Thus, support for the following TFD methods is included:

Cohen's Class RID:
DiscreteTFD Toolbox (GPL) - generate_TFDs_dtfd_oneil.m
binomial and born-jordan kernels
Time-Frequency Toolbox (Quantum Signal, academic license) - generate_TFDs_tftb_nickel.m
binomial and born-jordan kernels, defaults to non-analytic signal.
Subsampling TFDs not supported (yet) - i.e. signal samplerate must equal TFD bins.
RID-Rihaczek (GPL) - generate_TFDs_rid_rihajcek. (complex - for time-frequency phase-synchrony (TFPS)

Wavelets:
Matlab Wavelet Toolbox (Mathworks, academic license)  - generate_TFDs_matlab_wavelet_toolbox.m
Continuous wavelet transforms (cwt) support works with most wavelets implemented in the Matlab toolbox.
Scale axis is interpolated to uniform frequency.

NOTE: wavelet implementation is now unstable due to changes in the interpolation functions (to interpolate wavelet time-scale to time-frequency).  Needs to be fixed.

Note: Subsampling TFDs surfaces - i.e. signal samplerate greater than TFD time sampling rate uses the Matlab griddata function (for wavelets and the DiscreteTFD Toolbox), and is notably slow for large datasets.  The Time-Frequency Toolbox is not slow for this operation.  This slowdown can be avoided by always having the samplerate equal the TFD time sample rate.

Sub-divisions/directories within the Psychophysiology Toolbox

Note: Subsampling TFDs surfaces - i.e. signal samplerate greater than TFD time sampling rate uses the

Components

The primary aim of this toolbox is to conduct PCA in the time, freq, and time-freq domains.  A complementary secondary aim is to allow component selection with predefined windows, using all the same plotting and export functions.  This facillitates comparisons between PCA and predefined component selection by generating them in the identical environment.

Specifying in bins - The components toolbox currently accepts specification of time and freq ranges only in bins, rather than in milliseconds and Hz.  Because bins can span large ranges of milliseconds or Hz depending on windows, subsampling, and resampling, bins have seemed less confusing.  Specification in millliseconds and Hz may be added in the future.

Supported Operations
Data Processing

The primary aims of the data processing backend is to handle basic processing of large sets of data spanning many subjects, and to facilitate large numbers of comparisons within such datasets.  For example, the toolbox has been used to create average and trial aggregate datasets across, and to extract component measures from, datasets with over 2000 subjects with ERP and peripheral data.  

Specifying in ms and Hz - The Data Processing toolbox accepts all parameters in time (ms) and freq (Hz) units, instead of bins as the Components toolbox does. 

Supported Operations
Data Import

Currently Neuroscan and BioSemi BDF data formats are supported for automated data import.  Toolbox functions can import continuous as well as epoched data for Neuroscan files, and continuous data for BioSemi (uses opendbdf and readbdf scripts released by BioSemi) .  An epoching function allows epoching of continuous data.  Data can also be rereferenced in any manner with the rereference function (uses Neuroscan .ldr or similar files).  Also included is a detailed description of the format required by the toolboxes -- the format written by the Data Import toolbox.  The data format is designed to be relatively easy to construct, such that importing ascii data into this format should be possible by most researchers.

General

This contains a number of small functions that apply across a number of functions that didn't fit anywhere else.

Contact

For further information, questions, or feedback, please contact:

Edward Bernat, Ph.D.
Department of Psychology
1147 Biology/Psychology Building
University of Maryland
College Park, MD 20742

Fax:        (301) 405-5915
email:    ebernat@umd.edu