Difference between revisions of "PhysBox: The Psychophysiology Toolbox"

From Addiction Research Laboratory
Jump to: navigation, search
(Procedure for Identifying Epoch/Trial to include in pop_MarkEpochs)
 
(25 intermediate revisions by 3 users not shown)
Line 1: Line 1:
Note: no longer relevant to ARL setup procedure.
 
  
 
==Overview==
 
==Overview==
 +
PhysBox is a plugin that works in conjunction with the EEGLab toolbox.  PhysBox provides additional functionality and/or easier use for novice users to process psychophyiological data including EEG/ERP, startle EMG, skin conductance, heart rate, etc.  PhysBoX is designed to allow for the use of a very simple matlab script along with a simple tab-delimited text "Parameter" file for batch reduction.  In most instances, the user only needs to implement very minor (if any) changes to the script along with simple updates of parameters (e.g., path and file names) in the Parameter file.  Physbox is also designed to output by default numerous quantitiave and visual metrics to verify the integrity of the data reduction for all participants.  This facilitates identification of problematic subjects and/or other problems in the data reduction process.
  
 
==Installation==
 
==Installation==
 
===Introduction===
 
===Introduction===
Installation of both EEGLab and PhysBox is required to use PhysBox as PhysBox is a plugin for EEGLab.  There are two methods to install EEGLab and PhysBox:  1) via Subversion (SVN) or 2) via manual download of a zipped archive.   Installation via SVN is preferred because it will allow you to update your installations of EEGLab and PhysBox easily and as frequently as you like. It will also give you access to the most recent version of each, which is often not available through zipped archive.   
+
Installation of both EEGLab and PhysBox is required to use PhysBox as PhysBox is a plugin for EEGLab.  Both EEGLab and PhysBox are installed via Subversion (SVN). Installation via SVN is attractive because it will allow you to update your installations of EEGLab and PhysBox easily and as frequently as you like.  
  
  
Regardless of installation method, you will need to determine where to install EEGLab and PhysBox.  If the computers in your laboratory are on a network, we strongly suggest that you install EEGLab and PhysBox in their own folders on one central computer (e.g., a file server) that is accessible from all of your data processing workstations.  This provides two benefits.  First, when you install/update PhysBox and EEGLab, you will only need to install/update on this one computer rather than following these steps for every data processing workstation in your laboratory.  Second, this will guarantee that all your data processing workstations are using the same versions of EEGLab and PhysBox with the same configuration setup.  Of course, if you dont have a local network, you can simply install both on every workstation.  In this case, I suggest installing into appropriately named folders in Program Files.  It will work fine this way as well but will take more time to install/update.
+
To start, you will need to determine where to install EEGLab and PhysBox.  If the computers in your laboratory are on a network, we strongly suggest that you install EEGLab and PhysBox in their own folders on one central computer (e.g., a file server) that is accessible from all of your data processing workstations.  This provides two benefits.  First, when you install/update PhysBox and EEGLab, you will only need to install/update on this one computer rather than following these steps for every data processing workstation in your laboratory.  Second, this will guarantee that all your data processing workstations are using the same versions of EEGLab and PhysBox with the same configuration setup.  Of course, if you don't have a local network, you can simply install both on every workstation.  In this case, I suggest installing into appropriately named folders in Program Files.  It will work fine this way as well but will take more time to install/update.
  
  
Line 29: Line 29:
  
 
https://sccn.ucsd.edu/svn/software/eeglab
 
https://sccn.ucsd.edu/svn/software/eeglab
 
  
 
All other defaults are correct.  Press OK and the most current version of EEGLab will be downloaded into this folder.   
 
All other defaults are correct.  Press OK and the most current version of EEGLab will be downloaded into this folder.   
Line 41: Line 40:
  
 
for read/write access (developers only):  https://svn.code.sf.net/p/physbox/code/trunk/
 
for read/write access (developers only):  https://svn.code.sf.net/p/physbox/code/trunk/
 
  
 
All other defaults are correct.  Press OK and the most current version of PhysBox will be downloaded into this folder.
 
All other defaults are correct.  Press OK and the most current version of PhysBox will be downloaded into this folder.
 +
  
 
6.  In Windows Explorer, copy the file called '''eegplugin_PhysBox.m''' within the PhysBox folder.  Paste this file into the '''plugin''' folder inside of the EEGLab folder.  This will add PhysBox to the EEGLab GUI.   
 
6.  In Windows Explorer, copy the file called '''eegplugin_PhysBox.m''' within the PhysBox folder.  Paste this file into the '''plugin''' folder inside of the EEGLab folder.  This will add PhysBox to the EEGLab GUI.   
Line 51: Line 50:
  
 
====Mac====
 
====Mac====
Mac users should first read the documentation above for Windows.  The only difference is that you will not use TortoiseSVN and Windows Exploer.  Instead, you will use the built-in Subversion client.   
+
Mac users should first read the documentation above for Windows.  The only difference is that you will not use TortoiseSVN and Windows Explorer.  Instead, you will use the built-in Subversion client.   
  
 
First open the Terminal application.  
 
First open the Terminal application.  
Line 71: Line 70:
  
 
http://www.versionsapp.com/ [$60]
 
http://www.versionsapp.com/ [$60]
 
===Installation via zipped archive===
 
You can obtain zipped archives of EEGLab and PhysBox and extract these archives into the relevant folders if you do not want to use SVN.  However, in both instances, these may not be the most up to date versions of the software.  To update to a new version, delete all the files from the previous version before extracting the new version.
 
 
The current zipped archive for EEGLab can be obtained [http://www.sccn.ucsd.edu/eeglab/install.html here]
 
 
 
The current zipped archive for PhysBox can be obtained [https://dionysus.psych.wisc.edu:5001/fbsharing/BG2BOstk here]
 
 
 
After you have extracted each archive into their relevant folders on your server (or local computer), copy the file named ''eegplugin_PhysBox.m'' from the PhysBox folder and paste into the plugin folder within the EEGLab folder.
 
  
 
===Add PhysBox and EEGLab to the Matlab Path===
 
===Add PhysBox and EEGLab to the Matlab Path===
You will need to add a few lines of code to your ''startup.m'' file so that Matlab knows where to find the PhysBox and EEGLab functions.
 
 
This start-up file should be saved in the Matlab installation folder in Program Files (for Windows users).  The exact location of this file will vary installation to installation but generally should be found in ''C:\Program Files\Matlab\Toolbox\Local\''    You will know you are in the right place if you see a sample startup file called ''startupsav.m''.  If there is no file named ''startup.m'', you should create one in this folder and add the following lines of code.  Otherwise, add these lines to your existing ''startup.m'' file.
 
 
 
addpath(genpath('P:\Methods\Matlab\EEGLab'), '-frozen', '-end');
 
addpath(genpath('P:\Methods\Matlab\PhysBox'), '-frozen', '-end');
 
 
  
Of course, you will need to edit the path for each line to point to the location of your PhysBox and EEGLab folders.
+
Install our lab's custom startup file as per the instructions here: [[Installing Matlab and updating license and startup files]]
  
  
Line 209: Line 189:
  
 
pop_ProcessSet() calls are typically embedded in a ''for'' loop that loops through all entries in a parameter file (e.g.,
 
pop_ProcessSet() calls are typically embedded in a ''for'' loop that loops through all entries in a parameter file (e.g.,
 
+
<br>
 
for i = 1:CountSets(P)<br>
 
for i = 1:CountSets(P)<br>
 
:[EEG, P] = pop_ProcessSet(...)<br>
 
:[EEG, P] = pop_ProcessSet(...)<br>
Line 218: Line 198:
  
  
Demo scripts using pop_ProcessSet() are available for typical data processing for [https://128.104.130.200:5001/fbsharing/bJ76nuV3 Startle], [https://dionysus.psych.wisc.edu:5001/fbsharing/YEJvvoMw ERP], [Corrugator], and [Skin Conductance Response]
+
Demo scripts using pop_ProcessSet() are available for typical data processing for [http://dionysus.psych.wisc.edu/Open/DemoSTL.zip Startle], [http://dionysus.psych.wisc.edu/Open/DemoERP.zip ERP], [http://dionysus.psych.wisc.edu/Open/DemoCRG.zip Corrugator], and [http://dionysus.psych.wisc.edu/Open/DemoSCR.zip Skin Conductance Response]
  
 
The use of pop_ProcessSet() requires the set up and loading of a Parameter (P) file.  This file will be used to a) determine if subject is rejected or reduced already, b) provide input parameters for the pop functions for each subject, and c) receive output from the pop functions that is useful for data reduction integrity checks.
 
The use of pop_ProcessSet() requires the set up and loading of a Parameter (P) file.  This file will be used to a) determine if subject is rejected or reduced already, b) provide input parameters for the pop functions for each subject, and c) receive output from the pop functions that is useful for data reduction integrity checks.
Line 232: Line 212:
 
''P'': A parameter file which is a DAT file with input parameters for all processing steps for every subject.  This P file should have already been loaded into the workspace through a call to pop_GetParameters().  More information about this P file is provided in the appropriate section below<br><br>
 
''P'': A parameter file which is a DAT file with input parameters for all processing steps for every subject.  This P file should have already been loaded into the workspace through a call to pop_GetParameters().  More information about this P file is provided in the appropriate section below<br><br>
 
''SubjectIndex'': Index (row) of the current subject in the P file to obtain parameters.  If you are calling pop_ProceesSet() in a ''for i = 1:CountSets(P)'' loop as described above, SubjectIndex is simply ''i''<br><br>
 
''SubjectIndex'': Index (row) of the current subject in the P file to obtain parameters.  If you are calling pop_ProceesSet() in a ''for i = 1:CountSets(P)'' loop as described above, SubjectIndex is simply ''i''<br><br>
''ParameterIndex'': Optional index to add onto parameter field names in the P file when the                same pop function will be called multiple times in one reduction.  For example, ''SaveSet'' requires a parameter field named 'ssFile'.  ''SaveSet'' is often called multiple times in one reduction script.  Therefore separate calls to pop_ProcessSet() for each application of ''SaveSet'' will use a ParameterIndex of 1, 2, 3, etc respectively and the P file will include fields labeled 'ssFile1', 'ssFile2', 'ssFile3', etc<br>
+
''ParameterIndex'': Optional index to add onto parameter field names in the P file when the                same pop function will be called multiple times in one reduction.  For example, ''SaveSet'' requires a parameter field named 'ssFile'.  ''SaveSet'' is often called multiple times in one reduction script.  Therefore separate calls to pop_ProcessSet() for each application of ''SaveSet'' will use a ParameterIndex of 1, 2, 3, etc respectively and the P file will include fields labeled 'ssFile1', 'ssFile2', 'ssFile3', etc:<Br><br>
 
:[EEG, P] = pop_ProcessSet(EEG, 'SaveSet', i, 1)
 
:[EEG, P] = pop_ProcessSet(EEG, 'SaveSet', i, 1)
 
:[EEG, P] = pop_ProcessSet(EEG, 'SaveSet', i, 2)
 
:[EEG, P] = pop_ProcessSet(EEG, 'SaveSet', i, 2)
Line 260: Line 240:
 
:This numeric field contains the SubID
 
:This numeric field contains the SubID
 
;SubIDDigits
 
;SubIDDigits
:This numeric field indictes how many characters should be preserved when converting SubID to character for appending to filenames.  This allows for padding shorter SubIDs with zeros.  For example, if you list a SubID of 18 and SubIDDigits of 4, the character version of SubID will be '0018'
+
:This numeric field indictes how many characters should be preserved when converting SubID to character for appending to filenames.  This allows for padding shorter SubIDs with zeros and/or SubIDs of different lengths.  For example, if you list a SubID of 18 and SubIDDigits of 4, the character version of SubID will be '0018'
 
;Rejected
 
;Rejected
 
:This numeric field indicates if the subject has been rejected for future data processing.  1= Rejected, 0= Not Rejected.  This allows you to retain a record of subjects that you will not include in final processing and analysis b/c of data or other problems.  This field can also take on a value of -1 if a subject is 'Auto-Rejected' by ''pop_ProcessSet()''.  This will happen if the script attempts to open the original raw data file but does not find it due to a filename error (or b/c it is truly missing).  This allows your script to continue without crashing, and you can later set the Rejected field back to 0 after fixing the problem and re-run the script to reduce this individual subject.
 
:This numeric field indicates if the subject has been rejected for future data processing.  1= Rejected, 0= Not Rejected.  This allows you to retain a record of subjects that you will not include in final processing and analysis b/c of data or other problems.  This field can also take on a value of -1 if a subject is 'Auto-Rejected' by ''pop_ProcessSet()''.  This will happen if the script attempts to open the original raw data file but does not find it due to a filename error (or b/c it is truly missing).  This allows your script to continue without crashing, and you can later set the Rejected field back to 0 after fixing the problem and re-run the script to reduce this individual subject.
Line 271: Line 251:
 
;Reduced
 
;Reduced
 
:This numeric field should initially be set to 0 ('not reduced').  When a subject is reduced by script and you call ''pop_ReductionComplete()'' at the end of the data reduction loop, this function will set the Reduced field to 1.  This allows subsequent runs of the data reduction script to skip reduced subjects and only reduce new subjects in the Parameter file.  It is also used by ''pop_MultiSet()'' to determine which subjects to display figs, export notes, score, etc.
 
:This numeric field should initially be set to 0 ('not reduced').  When a subject is reduced by script and you call ''pop_ReductionComplete()'' at the end of the data reduction loop, this function will set the Reduced field to 1.  This allows subsequent runs of the data reduction script to skip reduced subjects and only reduce new subjects in the Parameter file.  It is also used by ''pop_MultiSet()'' to determine which subjects to display figs, export notes, score, etc.
;RootPath
+
;RawPath
:This character field should provide the full path to your RootPath folder.  This is the higher level folder that contains all the subject (InputPath) folders.  See notes above under File/Folder naming conventions for more details.
+
:This character field should provide the full path to your root folder that contains all subject data files.  In our lab, this folder is called RawData.  This is the higher level folder that contains all the subject (InputPath) folders.  See notes above under File/Folder naming conventions for more details.
 +
;OutPath
 +
:This character field should provide the full path to the folder that contains all aggregate data files (i.e., data files with data from all subjects).  In our lab, this folder is called Analysis. See notes above under File/Folder naming conventions for more details.
 
;Prefix
 
;Prefix
 
:This character field contains a string that is appended on the front of all files (data, figure, etc) that are created.  Use a unique Rrefix for each data reduction script to avoid overwriting files that have otherwise similar names.
 
:This character field contains a string that is appended on the front of all files (data, figure, etc) that are created.  Use a unique Rrefix for each data reduction script to avoid overwriting files that have otherwise similar names.
Line 314: Line 296:
  
  
Examples of typical/useful pop_MultiSet() calls are provided at the bottom (commented out) of each demo script ([https://128.104.130.200:5001/fbsharing/bJ76nuV3 Startle], [https://128.104.130.200:5001/fbsharing/YEJvvoMw ERP], [Corrugator], and [Skin Conductance Response])
+
Examples of typical/useful pop_MultiSet() calls are provided at the bottom (commented out) of each demo script.
  
 
===Sample PhysBox Processing Scripts, Parameter Files, and Data===
 
===Sample PhysBox Processing Scripts, Parameter Files, and Data===
 
'''Demonstration Sets by Measure'''
 
'''Demonstration Sets by Measure'''
  
:Startle: [https://dionysus.psych.wisc.edu:5001/fbsharing/bJ76nuV3 Script] [https://128.104.130.200:5001/fbsharing/nf99mlm9 Parameter File] [https://dionysus.psych.wisc.edu:5001/fbsharing/Pf0lei9M Data]
+
:Startle: [http://dionysus.psych.wisc.edu/Open/DemoSTL.zip Zip file]
  
:ERP: [https://dionysus.psych.wisc.edu:5001/fbsharing/A1yO0jzN Script] [https://128.104.130.200:5001/fbsharing/FBqVIoNa Parameter File] [https://dionysus.psych.wisc.edu:5001/fbsharing/XQLtSaff Data]
+
:ERP: [http://dionysus.psych.wisc.edu/Open/DemoERP.zip Zip file]
  
:Corrugator (time domain): [https://dionysus.psych.wisc.edu:5001/fbsharing/0Hy0oq7v zipped file]
+
:Corrugator (time domain): [http://dionysus.psych.wisc.edu/Open/DemoCRG.zip Zip file]
  
:Skin Conductance Response: [https://dionysus.psych.wisc.edu:5001/fbsharing/7KUSr59Q Script] [https://dionysus.psych.wisc.edu:5001/fbsharing/6rRVpCve Parameter File] [http://dionysus.psych.wisc.edu/methods/Matlab/PhysBox/Demos/DemoPiper2.zip Data]
+
:Skin Conductance Response: [http://dionysus.psych.wisc.edu/Open/DemoSCR.zip Zip file]
  
 
==Checking Data Reduction Integrity==
 
==Checking Data Reduction Integrity==
 
===Checking Event Table Structure===
 
===Checking Event Table Structure===
 
pop_EventCheck()
 
pop_EventCheck()
====Via GUI====
 
These instructions are designed to help you check the DMDX event codes so that you are sure all events are timed appropriately according to your study methods.  Thus, some of these parameters will vary based on the type of task and the task parameters.  The following instructions will use the DMDX startle parameters from HEFNER1 as an example.
 
 
HEFNER1 Study Events: 
 
::1 = shock
 
 
::11 = green cue in no shock block
 
::21 = red cue in predictable shock block 
 
::31 = blue cue in unpredictable shock block
 
::100 = habituation startle probes
 
 
::110 = ITI startle in no shock block
 
::111 = startle during green cue
 
::120 = ITI startle in predictable shock block
 
::121 = startle during red cue
 
::130 = ITI startle in unpredictable shock block
 
::131 = startle during blue cue 
 
 
::202= The third number means DMDX script order "2"
 
 
 
1) Open Matlab and type in eeglab at command prompt line
 
 
[[File:EventCheck1.JPG]]
 
 
 
2) In eeglab menu open "file", "import data", "from neuroscan.cnt file".  Select your .cnt test file and open (ex: [http://dionysus.psych.wisc.edu/Methods/Matlab/EEGLab/Demos/RawData/Hefner1DMDXEventCodes_Order3.cnt Demos/RawData/Hefner1DMDXEventCodes_Order3.cnt]). In load cnt dataset, select "OK".  In Dataset info--pop_newset select "OK" again.  Now the CNT file menu should be open.
 
 
 
[[File:EventCheck2.JPG]]
 
 
 
3) To check the first set of events, open "Tools" and "Check even table structure".  There will be a three separate  things you will check using this menu that are listed below as steps A-C.
 
 
Note: you will first need to enter the events into each space on this screen before performing steps A-C.  For this  example fill in the following information and select "OK":
 
 
::For "Check overall spacing for events" enter:  [110  111  120  121  130  131]
 
 
::For "Checking S1-S2 for events" enter: 
 
 
::::S1:    [11          21          31]
 
 
::::S2:    [111      121        131]
 
 
::For "Check ave serial position for events" enter:  [110      111        120        121        130        131]
 
 
 
[[File:EventCheck3.JPG|400px]]
 
 
 
'''A. Check overall spacing for events:'''
 
 
For this example we are checking the space between startle probes.  Go into the Matlab workspace and  double  click  "TimingArray".  This will automatically open a spreadsheet with four columns.  The fourth column is  the  space in between startle probes.  To change this column to ms, select "View" and "Numeric Array Format"  and  "short g".  For this example, time in between startle probes – should be at least 12 s!
 
 
 
[[File:EventCheck4.JPG]]
 
 
 
'''B. Check S1-S2 Spacing for Events'''
 
 
Check time in between 2 events
 
 
Check cue onset vs. cue startle
 
 
Go to Matlab workspace and double click "S1S2Array".  This will automatically open another spreadsheet with  four columns.  The fourth column has the timing information.In this example it should be 5 seconds.
 
 
 
'''C. Check average serial position for events'''
 
 
Counterbalancing Array
 
 
Go to Matlab workspace and double click "CB Array".  This will open a spreadsheet with three columns.  The  third  column has the serial counterbalancing information.  These should be roughly identical values.  In this  example,  there are 42 events here, so this should be equal to about 21.5
 
 
 
 
4)  These last few steps (A-C) will be repeated for another set of events.  To check the next set of events, open "Tools" and "Check even table structure". 
 
 
 
Note: you will first need to enter the events into each space on this screen before performing steps A-C.  For this  example fill in the following information and select "OK":
 
 
::For "Check overall spacing for events" enter:  [11  21  31]
 
 
::For "Checking S1-S2 for events" enter:   
 
 
::::S1:  [11          21          31] 
 
 
::::S2:  [110      120        130]
 
 
::For "Check ave serial position for events" enter:  [11  21  31]
 
 
 
'''A. Check overall spacing for events:'''
 
 
Checking the time between cues:
 
 
For this example we are checking the amount of time between cue presentations.  Go into the Matlab    workspace and double click "TimingArray".  This will automatically open a spreadsheet with four columns.  Copy  the  entire spreadsheet into Excel.  In Excel, create a fifth column that rounds the fourth column to seconds (Here  is  the formula to create the correct information: =Round(D1/1000,1)-6).  Then separate each block by trial type  by  adding a space between trial types (Ex: add row between the last 21 row and the first 11 row). 
 
 
For this example the new column created should have values that are roughly the same as all the ITI times for  your study, which are 19, 21, & 23. 
 
 
 
'''B. Check S1-S2 Spacing for Events'''
 
 
Check time in between cue onset vs. ITI startle
 
 
Go to Matlab workspace and double click "S1S2Array".  This will automatically open another spreadsheet with  four  columns. The fourth column has the timing information between the cue and ITI startle.  When looking at the  values in this column you will need to subtract 6 seconds (the cue duration) and this will tell you how much time  there is between the cue onset and startle.  In this example this should be 13 or 15 seconds. 
 
 
 
'''C. Check average serial position for events'''
 
 
Counterbalancing Array
 
 
Select cue events:
 
 
Go to Matlab workspace and double click "CB Array".  This will open a spreadsheet with three columns.  The  third  column has the serial counterbalancing information.  These should be roughly identical values.  In this  example,  they all should be 18.
 
 
 
5)  To check the last set of events, open "Tools" and "Check even table structure".  In this last check, we will only  be doing one check (Step B in previous checks).
 
 
Note: you will first need to enter the events into each space on this screen before performing the next step.  For  this example fill in the following information and select "OK":
 
 
::For "Checking S1-S2 for events" enter:   
 
 
::::S1:  [11          21          31] 
 
 
::::S2:  [1]
 
 
'''A. Check S1-S2 Spacing for Events'''
 
 
Check time in between cue onset vs. shock
 
 
Go to Matlab workspace and double click "S1S2Array".  This will automatically open another spreadsheet with  four  columns. The fourth column has the timing information between the cue onset and shock.  Sort colunm two  by event type.  For this example, each event type will have a different timing of the shock. 
 
 
For event 21 (predictable condition) the timing should be roughly 5.5s.  For event 31 (unpredictable condition),  the timing should be 5.5s or 18, 20, and 22, which are equivalent to shocks occuring at 12s, 14s, and 16s  post-cue. 
 
 
 
Created  by Rebecca Gloria & Kathryn Hefner, 2008-08-25
 
 
 
====Via Script====
 
====Via Script====
 
Demo EEGlab/Matlab script for checking event code count, timing/spacing and counterbalancing:  [https://128.104.130.200:5001/fbsharing/q98bzPkN CheckEventCodes.m]
 
Demo EEGlab/Matlab script for checking event code count, timing/spacing and counterbalancing:  [https://128.104.130.200:5001/fbsharing/q98bzPkN CheckEventCodes.m]
Line 483: Line 329:
 
pop_ViewRejects() and multiset processing (soon)
 
pop_ViewRejects() and multiset processing (soon)
  
===Procedure for Identifying Epoch/Trial to include in pop_MarkEpochs===
+
==PhysBox Functions==
1.  Open Check Startle file to find subjects with bad/artifact trials to reject.  Sort this file by “Final – N Bad Trials” for the task you are currently checking. Make sure you highlight ALL of the data before sorting.
+
===list each function here===
::a.  EX. P:\StudyData\KAYE1\RawData\Process\CheckSTL.xlsx
+
  
[[File:Epoch1.png]]
 
  
2.  Open Parameter file in Excel. If the study has some participants with 4-digit SubIDs and others with 5-digit SubIDs, there might be two Parameter files.
+
==PhysBox Listserv==
::a.  EX. P:\StudyData\KAYE1\RawData\Process\Kaye1_BaselineD1T1_STLParameters.dat
+
To join or leave the PhysBox Listserv, send a blank email from your relevant email account to either:
  
3. Open Matlab
+
join-physbox@lists.wisc.edu
  
4. Direct Matlab’s ‘Current Folder’ to the study’s RawData folder
+
leave-physbox@lists.wisc.edu
::a.EX. P:\StudyData\KAYE1\RawData
+
  
[[File:Epoch4.png]]
+
==Citing PhysBox==
  
5.  Open EEGLab by typing ‘eeglab’ in Matlab command window and pressing enter.  Important to do this before the next step otherwise otherwise Matlab will get stuck. The eeglab GUI will pop up.
+
Cite both PhysBox plugin and EEGLab toolbox
  
6. Open the *Study*_STL_Checks.m Matlab file
+
Curtin, J. J. (2011)PhysBox: The Psychophysiology toolbox.   An open source toolbox for psychophysiological data reduction within EEGLabhttp://dionysus.psych.wisc.edu/PhysBox.htm
::aEX. P:\StudyData\KAYE1\RawData\Process\ Kaye1_STL_Checks.m
+
::b.  Scroll to middle of page to line that says %% Check Select Figures for Manual Review to Identify Artifact Trials
+
::cCopy 2 lines of code starting with “P= pop_Get…” and “pop_MultiSet…” corresponding to the task you are working with. Paste into Matlab Command Window and press enter.
+
::d. This will automatically open all figures in that were flagged to review for that task. However, this will include some figures that we decided were good and have no bad trials. See SubID to compare to “Final – N Bad Trials” to know what Subs to look for bad trials.
+
  
[[File:Example.jpg]]
 
  
7.  Open EPHAll set file. In EEGlab Click: PhysBox ->Data load/save/close -> Load Set File. Find File in Subject’s Reduce folder:
+
A Delorme & S Makeig (2004) EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics. ''Journal of Neuroscience Methods'', 134:9-21
::a.  EX. P:\StudyData\KAYE1\RawData\1038\Reduce\ Base_D1_T1_STL_EPHAll1011.set
+
  
8. PhysBox -> Plotting -> View Set
+
==For Developers==
 +
https://svn.code.sf.net/p/physbox/code/trunk/
  
9.  Change scale in figure to match the Figure4Panel to make it easier to detect problem trials. Scale located to right of Value and left of +/- buttons.
+
svn+ssh://jjccurtin@svn.code.sf.net/p/physbox/code/trunk/
  
[[File:Example.jpg]]
+
https://sourceforge.net/p/forge/documentation/SVN%20and%20Project%20Upgrades/
  
10. Find Trial number for all bad/artifact trials. Trial number is marked (in blue) at the top of the epoch window.
+
[http://tortoisesvn.net/support.html  download the TortoiseSVN pdf]
  
11.  In Parameter file column “meTrials” enter the trial number that is bad and should be marked. Enter numbers in squiggly brackets {} and separate by spaces; e.g., {1 26 42}
+
[[Dialog Box GUI Examples]]
  
[[File:Example.jpg]]
+
==To Do and Future Functionality==
  
12.  Close FigurePanel Matlab figure. The next figure that was flagged to review will automatically pop up.
+
===To Do===
 +
*Need help for pop_DiagnosticFigure
  
13.  Close View Set in eeglab. Also in eeglab, click File -> Clear study / Clear all.  This last step is important because it helps to keep Matlab from freezing up.
 
 
14.  When ready to save, Save (icon in upper left) -> Yes; Then Exit Excel (x icon in upper right) and Do Not Save.
 
 
15.  Repeat this process for each task (e.g., baseline, NPU1, NPU2, etc).
 
 
16.  Do a preliminary check for mistakes for each task. 
 
::a.  Sort the CheckSTL.xlsx file for the correct task by “Final – N Bad Trials”
 
::b.  For each SubID in CheckSTL.xlsx that has a 1 or more in the “Final – N Bad Trials” column, check to make sure there are the correct amount of entries in the Parameters “meTrials” column for that SubID.
 
::::i.  For example, if SubID 9999 has a ‘2’ in the “Final – N Bad Trials” column for the NPU1 task, check to see that SubID 9999 has {x y} in the “meTrials” column on the NPU1 Parameter file rather than {x}, {x y z}, etc.
 
 
[[File:Example.jpg]]
 
 
::c.  Check for wrong additions; times when a value was added to an incorrect SubID’s “meTrials” cell. 
 
::::i.  Sort the CheckSTL.xlsx file for the correct task by “Final – N Bad Trials”
 
::::ii.  At the bottom of the “Final – N Bad Trials” column that was just sorted, there is a number that totals the column.  Compare this number to the number of total values entered into the “meTrials” column for that particular task by counting the total number of values in the “meTrials” column to see if it matches the number at the bottom of the sorted “Final – N Bad Trials” column. 
 
::::::1.  EX. {3} + {21} + {4 9} = 4 values
 
 
[[File:Example.jpg]]
 
 
==PhysBox Functions==
 
===list each function here===
 
 
 
==Version Reports==
 
'''v2.0.0 (2012-02-08)'''
 
*Removed pop_ProcessSets() and replaced with pop_ProcessSet() and pop_MultiSet()
 
*Modified Parameter file fields to reflect this simpler processing stream.  Includes rename of Reject to Rejected, replacement of multiple Reduced# fields with one field called Reduced.  Replacement of File0 with csFile.  Replacement of FileN with ssFileN (e.g., ssFile1, ssFile2, etc).  Replacement of Checked1 field with Checked. 
 
*Updated STL and ERP demo files (scripts and Parameter file) to reflect these changes
 
*Changed pop_GrandAverage() to pop_Add2Gnd to better reflect its function.  Errors no long crash the script.  Instead, errors are added to field called agWarning.
 
 
 
'''v1.19.0 (2012-02-04)'''
 
 
*Added pop_LoadAnt() for loading ANT files.  Included in GUI and pop_ProcessSets().  Requires one parameter (csTrigger set to on or off) for multiset processing
 
*Added pop_DiagnosticFigure().  Included in pop_ProcessSets().  Requires 2 parameters (deFiles and deFigChan) for multiset processing.  Modified STL multiset demo to include it. 
 
*Removed figure from notes_CreateAvg().  No longer necessary with the development of pop_DiagnosticFigure()
 
*Modified data file names to add '''Prefix''' to the front of all output data files.  This allows very general names for File1, File2, etc (e.g., EPHAll, EPHFin, AVG, GND).
 
 
==Potential Future Functionality==
 
 
===John's top priorities===
 
 
*AppendNotes has bug when new note is added that is shorter than previous note for same subject, it will not erase all of previous note.
 
*AppendNotes has bug when new note is added that is shorter than previous note for same subject, it will not erase all of previous note.
  
 
*AvgFigure should take and (optional) parameter which lists events to plot
 
*AvgFigure should take and (optional) parameter which lists events to plot
  
*Estimate missing data for STL
+
*Check on NaNs for subjects with no epochs in SAFE.  Why are fields in sets earlier then EPHFin NaN?
 
+
* Check on NaNs for subjects with no epochs in SAFE.  Why are fields in sets earlier then EPHFin NaN?
+
  
 
*Make the method input parameter of ScoreERP a cell array, rather than a string.  It would be fun if we had the option to specify unique scoring methods for each of our windows. perhaps the current setup (ie, single method) could be the default if only one method were passed?
 
*Make the method input parameter of ScoreERP a cell array, rather than a string.  It would be fun if we had the option to specify unique scoring methods for each of our windows. perhaps the current setup (ie, single method) could be the default if only one method were passed?
  
*reject based  on point by point exceeding SDs from mean (i.e., confidence envelope around full trial)
+
*Demo script and Parameter file for CRG (time and frequency) and SCR
 
+
*Check for each parameter in sub functions and output descriptive error when not found
+
 
+
*Update demo script and Parameter file for CRG and SCR
+
  
 
*Save vs. Saveas in GUI
 
*Save vs. Saveas in GUI
 
*Another check of GUI functionality following last update
 
  
 
*Create notes_ScoreWindows() and notes_ScoreERP() based on notes_ScoreStartle()
 
*Create notes_ScoreWindows() and notes_ScoreERP() based on notes_ScoreStartle()
Line 593: Line 382:
  
 
*Systematic completion of help for notes and support functions
 
*Systematic completion of help for notes and support functions
 
*Demo script for CRG in frequency domain
 
  
 
*fix warning message precision error in AdjTime()
 
*fix warning message precision error in AdjTime()
Line 600: Line 387:
 
*Figure out how setname is set
 
*Figure out how setname is set
  
===Near term changes===
 
 
*Create a ReadDat and WriteDat that works with tdfread/write but converts char fields to cell rather than char array.   
 
*Create a ReadDat and WriteDat that works with tdfread/write but converts char fields to cell rather than char array.   
  
Line 608: Line 394:
  
 
*make change gain (e.g., for PRB) function for CON files
 
*make change gain (e.g., for PRB) function for CON files
 
*Function to mark specific epochs for reject: pop_MarkEpoch().  Consider if pop_DeleteEpoch() with Indices enough?
 
  
 
*Make all parameter calls like ButterworthFilter with option to include ParameterIndex in fieldname in pop_ProcessSet().  Definitely need ParameterIndex for ScoreERP and Score Windows
 
*Make all parameter calls like ButterworthFilter with option to include ParameterIndex in fieldname in pop_ProcessSet().  Definitely need ParameterIndex for ScoreERP and Score Windows
  
 
*Warning for ExportScores function if subID is in file already.  Maybe save in notes like agWarning?
 
*Warning for ExportScores function if subID is in file already.  Maybe save in notes like agWarning?
 
*Need better DiagnosticFigure for ERP
 
  
 
*Add LoadSet to pop_ProcessSet for later call in script to loading set files that arent currently in the processing stream  
 
*Add LoadSet to pop_ProcessSet for later call in script to loading set files that arent currently in the processing stream  
Line 622: Line 404:
  
 
*ExportScores takes list of scores
 
*ExportScores takes list of scores
 
*Think more carefully about eeg_FastFourier.  Compare to pwelch, etc
 
  
 
*Figure out when to use eeg_hist and eegh.  Generally consider what COMs to record.  Possibly Add new COM field for multiset?
 
*Figure out when to use eeg_hist and eegh.  Generally consider what COMs to record.  Possibly Add new COM field for multiset?
Line 639: Line 419:
 
*Finish pop_CheckERP()
 
*Finish pop_CheckERP()
  
*Function to find peak latency of components (in various windows) in grand average to use in selection of scoring windows.
+
*Consider what happens to notes fields when EEG= emptyset for functions like pop_CreateAvg and pop_AverageWaveform.  If this is a second (or later) reduction, with the old notes remain?
  
*Integrate methods from MASS
+
===Possible Future Functionality===
http://openwetware.org/wiki/Mass_Univariate_ERP_Toolbox
+
*Consider ways to mark bad trials and review visually with independent reviewers in PhysBox GUI
  
*Consider what happens to notes fields when EEG= emptyset for functions like pop_CreateAvg and pop_AverageWaveform. If this is a second (or later) reduction, with the old notes remain?
+
*Integrate methods from MASS: http://openwetware.org/wiki/Mass_Univariate_ERP_Toolbox
  
*better screen processing info for EventRecode.  Include what is being recoded to what
 
 
===Under consideration===
 
 
*consider added a field in output file and notes output for mean in 150-250 for startle.  It would be very similar to basedeflect scoring currently.
 
*consider added a field in output file and notes output for mean in 150-250 for startle.  It would be very similar to basedeflect scoring currently.
 
*Consider handling accuracy by deleting trials rather than within pop_CreateAvg().  Makes it similar to processing stream for STL and EMG.  Could also use a much simpler CreateAvg() function as well.
 
  
 
*need a REMOVE SCORES function to get rid of ERP scores from scores field that don’t work.
 
*need a REMOVE SCORES function to get rid of ERP scores from scores field that don’t work.
Line 661: Line 436:
 
http://visual.cs.utsa.edu/research/projects/eegvis
 
http://visual.cs.utsa.edu/research/projects/eegvis
  
==PhysBox Listserv==
+
*Estimate missing data for STL
To join or leave the PhysBox Listserv, send a blank email from your relevant email account to either:
+
  
join-physbox@lists.wisc.edu
+
*reject based  on point by point exceeding SDs from mean (i.e., confidence envelope around full trial)
  
leave-physbox@lists.wisc.edu
+
*Check for each parameter in sub functions and output descriptive error when not found
  
==Citing PhysBox==
+
*Need better DiagnosticFigure for ERP
  
Cite both PhysBox plugin and EEGLab toolbox
+
*Think more carefully about eeg_FastFourier.  Compare to pwelch, etc
 +
*Function to find peak latency of components (in various windows) in grand average to use in selection of scoring windows.
  
Curtin, J. J. (2011).  PhysBox: The Psychophysiology toolboxAn open source toolbox for psychophysiological data reduction within EEGLab.  http://dionysus.psych.wisc.edu/PhysBox.htm
+
*better screen processing info for EventRecodeInclude what is being recoded to what
 
+
 
+
A Delorme & S Makeig (2004) EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics. ''Journal of Neuroscience Methods'', 134:9-21
+
 
+
==For Developers==
+
https://svn.code.sf.net/p/physbox/code/trunk/
+
 
+
svn+ssh://jjccurtin@svn.code.sf.net/p/physbox/code/trunk/
+
 
+
 
+
https://sourceforge.net/p/forge/documentation/svn%20-%20Beta/
+
 
+
 
+
 
+
[http://tortoisesvn.net/support.html  download the TortoiseSVN pdf]
+
 
+
[[Dialog Box GUI Examples]]
+
  
  
[[Category:Obsolete]]
+
[[Category:OnWebsite]]

Latest revision as of 20:58, 20 August 2018

Overview

PhysBox is a plugin that works in conjunction with the EEGLab toolbox. PhysBox provides additional functionality and/or easier use for novice users to process psychophyiological data including EEG/ERP, startle EMG, skin conductance, heart rate, etc. PhysBoX is designed to allow for the use of a very simple matlab script along with a simple tab-delimited text "Parameter" file for batch reduction. In most instances, the user only needs to implement very minor (if any) changes to the script along with simple updates of parameters (e.g., path and file names) in the Parameter file. Physbox is also designed to output by default numerous quantitiave and visual metrics to verify the integrity of the data reduction for all participants. This facilitates identification of problematic subjects and/or other problems in the data reduction process.

Installation

Introduction

Installation of both EEGLab and PhysBox is required to use PhysBox as PhysBox is a plugin for EEGLab. Both EEGLab and PhysBox are installed via Subversion (SVN). Installation via SVN is attractive because it will allow you to update your installations of EEGLab and PhysBox easily and as frequently as you like.


To start, you will need to determine where to install EEGLab and PhysBox. If the computers in your laboratory are on a network, we strongly suggest that you install EEGLab and PhysBox in their own folders on one central computer (e.g., a file server) that is accessible from all of your data processing workstations. This provides two benefits. First, when you install/update PhysBox and EEGLab, you will only need to install/update on this one computer rather than following these steps for every data processing workstation in your laboratory. Second, this will guarantee that all your data processing workstations are using the same versions of EEGLab and PhysBox with the same configuration setup. Of course, if you don't have a local network, you can simply install both on every workstation. In this case, I suggest installing into appropriately named folders in Program Files. It will work fine this way as well but will take more time to install/update.


NOTE: Matlab will need to be configured to recognize EEGLab and PhysBox by adding their folders to the Matlab path. This step is accomplished after installation of both EEGLab and PhysBox and is described below.


NOTE: PhysBox should work with most recent versions of EEGLab and Matlab. Our lab tends to be up to date within the past year for versions of both. In addition to the base package for Matlab, PhysBox filtering requires the Signal Processing Toolbox.

Installation via SVN

Subversion (SVN) provides version control for software developers. It is used by both the EEGLab and PhysBox developers. The files are hosted on a central repository on a server on the web and users can download the most up to date copy of these files very easily. To accomplish this, you need to interact with the SVN server via an SVN client. The client that you use (and therefore the steps to install or update the files) varies by OS. Follow the instructions for your OS

Windows

Windows users will use the TortoiseSVN client. TortoiseSVN is very simple to use. It is a shell program that will add context menus to Windows Explorer, which will allow you to download/update both EEGLab and PhysBox directly using Windows Explorer.

1. Go to the TortoiseSVN download page and download and install the correct version of this software (32 bit or 64 bit). You will need to restart your computer after installing TortoiseSVN before your first use.

2. Determine where you will install EEGLab (see comments above). Create a folder called EEGLab in this location.

3. Right click on this folder in Windows Explorer and select SVN Checkout.... In the URL of Repository box, enter the following URL (You will only need to do this once. Future updates will remember this URL):

https://sccn.ucsd.edu/svn/software/eeglab

All other defaults are correct. Press OK and the most current version of EEGLab will be downloaded into this folder.


4. Now determine where you will install PhysBox (see comments above). Create a folder called PhysBox in this location.

5. Right click on this folder in Windows Explorer and select SVN Checkout.... In the URL of Respository box, enter one of the following URLs:

for anonymous access: svn://svn.code.sf.net/p/physbox/code/trunk/

for read/write access (developers only): https://svn.code.sf.net/p/physbox/code/trunk/

All other defaults are correct. Press OK and the most current version of PhysBox will be downloaded into this folder.


6. In Windows Explorer, copy the file called eegplugin_PhysBox.m within the PhysBox folder. Paste this file into the plugin folder inside of the EEGLab folder. This will add PhysBox to the EEGLab GUI.


NOTE: In the future, you can update either EEGLab or PhysBox to their most current version by right clicking on the appropriate folder and selecting SVN Update. This will bring up a dialog box where you will again select the appropriate Repository URL from a drop down menu (TortoiseSVN will remember your previous entries). All other defaults will be correct. Click OK and your software will be up to date! If you update PhysBox, you will still need to manually copy the eegplugin_PhysBox.m file to the plugin folder for EEGLab to keep the GUI current.

Mac

Mac users should first read the documentation above for Windows. The only difference is that you will not use TortoiseSVN and Windows Explorer. Instead, you will use the built-in Subversion client.

First open the Terminal application. (An introduction to Terminal is here: http://macapper.com/2007/03/08/the-terminal-an-introduction/)

To get an initial copy of the current version of PhysBox, type:
svn checkout -d physbox 'http://svn.code.sf.net/p/physbox/code/trunk'

To update an existing copy to the latest version in the repository:
cd physbox; svn update

Repeat this process with the URL for EEGLab to get or update a copy of it.

If you would like to explore other SVN clients with GUIs for the Mac:

http://www.syntevo.com/smartsvn/download.html [free]

http://www.zennaware.com/cornerstone/ [$60]

http://www.versionsapp.com/ [$60]

Add PhysBox and EEGLab to the Matlab Path

Install our lab's custom startup file as per the instructions here: Installing Matlab and updating license and startup files


After you have modified (or created) your startup.m file, restart Matlab and test your installation with the following tests:

Type eeglab at the Matlab command prompt. The EEGlab GUI should start. If it does, you have successfully installed EEGLab.


If PhysBox is the first menu option at the top left of the EEGLab GUI, you have installed the PhysBox GUI correctly.


Type help pop_ProcessSet. If this command returns help for this function, you have added PhysBox to the Matlab path correctly.

Recommended EEGLab configuration changes

1. Type eeglab at the Matlab command prompt


2. From the GUI, select File:Memory and Other Options


3. Under STUDY options, unselect the box which indicates If set, save not one but two files....


4. Under Memory Options, unselect the box which indicates If set, use single precison...


5 Under Folder Options, select the box which indicates If set, when browsing to open a new data...

6. Under EEGLAB chat option, unselect the box which indicates if set, enable EEGLAB chat...


NOTE: Depending on your OS and your level of permissions, you may need to change the location of your Options file. The path to the options file can be changed via the button at the bottom of the dialog box. If necessary, select a location that you have permission to write/modify files.

NOTE2: It may be more direct to edit the options file by typing edit eeg_optionsbackup at the command line


Final Recommendation: You may also prefer to change the default y-axis scale when viewing data. To do this, type edit eegplot at the Matlab command prompt. Use Edit:Find and Replace from menu of the editor to search for this line:
try, g.spacing; catch, g.spacing = 0; end;

Change g.spacing=0 to an appropriate value. I suggest 400.

File Naming and Directory Structure Conventions

Directory structure

MyStudy -> MyRawDataRootDir -> MySingleSubDirs (1 per subject; contains raw files) -> MyReducedDataDir (contains processed intermediate files and logs)

1. For each study there’s a study folder (one folder will have raw data -root path for all data files) root path a. inside root path individual folder for each subject named with the subject ID number (these files are never modified). If you need to do anything by hand it would go here. input path i. within each subjects folder there is a reduce folder, where processed data is saved (can be recreated easily) output path 2. Files names somestingsubid.whatever

Data file types and formats

CNT (int16, int32) vs. SMA vs. SET


CON vs. EPH vs. AVG vs GND



xxxx_yyy.aaa

where:

xxx = local file info (applied processing) yyy = subid and/or runid type info (root name) aaa = file type extension

PhysBox function names and types

pop_TitleCase

notes_TitleCase

support functions


1. pop_TileCase-work at the command line, called by gui. If you provide a single parameter a gui will pop up to ask for the rest of the parameters necessary.

2. notes_TitleCase-most processing makes notes saved in the data structure to review if things work well.

3. Support functions-from multiple places (inconsistent naming), never called directly

Parameters in functions and Parameter file

time in ms

all entries in cell arrays

Windows for epochs

ChanList of channel labels ('all' 'exclude')

The EEG Data Structure

Read documentation on the EEG data structure from the EEGLab Wiki



NEED TO describe the notes and scores fields that are unique to PhysBox

The EEGLab and Physbox GUI

PhysBox Processing by Script

Overview

pop_ProcessSet()

This function is the main workhorse for data processing by script. It is a liaison between the individual pop functions and the parameter (P) file. The P file provides information about the parameters needed for any specific pop function for each subject. The P file also tracks if subjects have been rejected and/or reduced already. Finally the pop functions write output (via notes functions) back to the P file with assistance from pop_ProcessSet().

pop_ProcessSet() calls are typically embedded in a for loop that loops through all entries in a parameter file (e.g.,
for i = 1:CountSets(P)

[EEG, P] = pop_ProcessSet(...)
[EEG, P] = pop_ProcessSet(...)
...
[EEG, P] = pop_ProcessSet(...)

end


Demo scripts using pop_ProcessSet() are available for typical data processing for Startle, ERP, Corrugator, and Skin Conductance Response

The use of pop_ProcessSet() requires the set up and loading of a Parameter (P) file. This file will be used to a) determine if subject is rejected or reduced already, b) provide input parameters for the pop functions for each subject, and c) receive output from the pop functions that is useful for data reduction integrity checks.


USAGE: [EEG, P] = pop_ProcessSet(EEG, Function, P, SubjectIndex, ParameterIndex)
The calls to pop_ProcessSet() provide a standard interface to all pop functions that require you to input only (up to) five simple parameters to this function in your processing scripts. They are defined as follows:


INPUT PARAMETERS
EEG: an EEG set file that will be the target for the associated pop function indicated in Function

Function: A character string that matches the name of a pop function without the 'pop_' and the '()'. This string is case sensitive and should use TitleCase

P: A parameter file which is a DAT file with input parameters for all processing steps for every subject. This P file should have already been loaded into the workspace through a call to pop_GetParameters(). More information about this P file is provided in the appropriate section below

SubjectIndex: Index (row) of the current subject in the P file to obtain parameters. If you are calling pop_ProceesSet() in a for i = 1:CountSets(P) loop as described above, SubjectIndex is simply i

ParameterIndex: Optional index to add onto parameter field names in the P file when the same pop function will be called multiple times in one reduction. For example, SaveSet requires a parameter field named 'ssFile'. SaveSet is often called multiple times in one reduction script. Therefore separate calls to pop_ProcessSet() for each application of SaveSet will use a ParameterIndex of 1, 2, 3, etc respectively and the P file will include fields labeled 'ssFile1', 'ssFile2', 'ssFile3', etc:

[EEG, P] = pop_ProcessSet(EEG, 'SaveSet', i, 1)
[EEG, P] = pop_ProcessSet(EEG, 'SaveSet', i, 2)
[EEG, P] = pop_ProcessSet(EEG, 'SaveSet', i, 3)


OUTPUT PARAMETERS
EEG: the EEG set file updated after application of the pop function indicated by Function

P: the Parameter file updated (possibly depending on pop function)

The Parameter File P

The Parameter file is a tab-delimited text file (typically ending in .dat extension) that is used by pop_ProcessSet() and pop_MultiSet() to obtain input parameters for the associated pop functions and to save output parameters (to check data reduction integrity) from the application of these pop functions.


On disk, the Parameter file is a Rows X Columns DAT file where individual subjects are recorded in separate rows and input/output parameter fields are saved in separate columns. The field names are case sensitive. No specific ordering of fields is necessary but it is good practice to use a sensible ordering (e.g., required fields first, remaining fields in the order that they are called by processing script). The Parameter files are best viewed and edited in Excel but should always be saved as .dat text files. It is also important that you close the Parameter file before running your scripts.


A call to [P] = pop_GetParameters() is used to import the data in this Parameter file into a data structure, P, that has different fields for each input/output parameter field/column. These fields can contain varied data types including double, char, and cell arrays.


The P data structure created from the Parameter file is intended to be used by a specific script that contains calls to pop_ProcessSet() or by command line calls to pop_MultiSet(). Sample Parameter files and associated data reduction scripts are available for the reduction of Startle ([Script]; [Parameter file]), ERP ([Script]; [Parameter file]), Corrugator([Script]; [Parameter file]), Skin Conductance Response([Script]; [Parameter file]). You should review a couple of these sample Parameter files before reading further.

Input Parameter Fields

There are a handful of input parameter fields that are required in all Parameter files. As noted earlier, ordering does not matter but I prefer to list them at the start of the Parameter file in this order...

SubID
This numeric field contains the SubID
SubIDDigits
This numeric field indictes how many characters should be preserved when converting SubID to character for appending to filenames. This allows for padding shorter SubIDs with zeros and/or SubIDs of different lengths. For example, if you list a SubID of 18 and SubIDDigits of 4, the character version of SubID will be '0018'
Rejected
This numeric field indicates if the subject has been rejected for future data processing. 1= Rejected, 0= Not Rejected. This allows you to retain a record of subjects that you will not include in final processing and analysis b/c of data or other problems. This field can also take on a value of -1 if a subject is 'Auto-Rejected' by pop_ProcessSet(). This will happen if the script attempts to open the original raw data file but does not find it due to a filename error (or b/c it is truly missing). This allows your script to continue without crashing, and you can later set the Rejected field back to 0 after fixing the problem and re-run the script to reduce this individual subject.
RejectNotes
This character field is used primarily to store notes on why you have rejected a subject. However, pop_ProcessSet() will add notes to this field if it auto-rejects a subject.
Comments
This character field is never used directly by PhysBox functions. As such, it is not really required. However, it provides a nice place to keep track of notes about a subject that might be relevant for interpreting their data.
Checked
This numeric field is used by pop_CheckStartle() and pop_CheckERP(). If you are not using those functions, it is not required. It is set to 1 (manually by you) once you have checked the reduction for a participant. Future calls to the pop_Check functions will then ignore this subject to save you time. This field should be initially set to 0 when the subject has not been checked.
Reduced
This numeric field should initially be set to 0 ('not reduced'). When a subject is reduced by script and you call pop_ReductionComplete() at the end of the data reduction loop, this function will set the Reduced field to 1. This allows subsequent runs of the data reduction script to skip reduced subjects and only reduce new subjects in the Parameter file. It is also used by pop_MultiSet() to determine which subjects to display figs, export notes, score, etc.
RawPath
This character field should provide the full path to your root folder that contains all subject data files. In our lab, this folder is called RawData. This is the higher level folder that contains all the subject (InputPath) folders. See notes above under File/Folder naming conventions for more details.
OutPath
This character field should provide the full path to the folder that contains all aggregate data files (i.e., data files with data from all subjects). In our lab, this folder is called Analysis. See notes above under File/Folder naming conventions for more details.
Prefix
This character field contains a string that is appended on the front of all files (data, figure, etc) that are created. Use a unique Rrefix for each data reduction script to avoid overwriting files that have otherwise similar names.


While not strictly required, the next set of input parameter fields are the ssFile# fields. These fields are used when you call SaveSet within pop_ProcessSet(). These are character fields that are used to determine output file names for your data files. Therefore if you are saving any EEG files for each subject, you will have to include these fields. For example, in the typical startle reduction, we first save a raw epoched file with all trials (ssFile1 = EPHAll), followed by a final epoched file with artifactual trials rejected (ssFile2 = EPHFin), and finally an averaged file across event types (ssFile3 = AVG). See notes about the ParameterIndex in pop_ProcessSet() above to understand how individual calls to SaveSet unambigiously link to the appropriately numbered ssFile field.


The remaining input parameter fields are each linked to calls to specific pop functions within pop_ProcessSet(). Each pop function requires its own parameters with specific field names. You can see a list of the parameters and their field names for each pop function by typing help pop_ProcessSet() at the command line. These field names do have some consistent structure. Specifically each field name begins with two lower case letters that reflect the two words in the pop function (e.g., ss for SaveSet, ee for ExtractEpochs, de for DeleteEpochs, etc). Following these two lowercase letters is the actual descriptive parameter name in TitleCase.


There is one final 'field' associated with the input parameters. This field is called 'StartNotes' and is typically filled with a series of 'XXXXX' for all subjects. This field is not required but serves as a nice visual separator between the input parameter fields and the output parameter fields.

Output Parameter Fields

An attractive feature of the PhysBox pop functions is that many call associated notes functions (with same TitleCase name as pop function). These notes functions add to a 'notes' field in the EEG set file. If you call AppendNotes via pop_ProcessSet() or pop_MultiSet(), these notes fields in each EEG file will be appended to the end of your Parameter file in the row associated with that subject. This puts many details about the data reduction in one place for you to review to confirm the integrity of your data reduction. These output parameter fields also use a semi-consistent name structure. Specifically they begin with two lower case letters and a '_' (to distinguish them from the input parameters). The lower case letters indicate which pop function produced these output parameters. The remainder of the field name uses TitleCase to provide more detail about the specific parameter.


It is good practice to put a call to pop_ProcessSet() with AppendNotes as the function near the end of your reduction script loop. Alternatively, you can append these output parameters after data reduction at any point using pop_MultiSet() with AppendNotes as the function. Make sure you use the EEG file with the most complete set of notes. This is typically the last EEG file created in the data reduction stream for a subject.

pop_MultiSet()

This function is designed to execute pop functions on all Reduced (and typically not Rejected) subjects in a parameter file without the need to put it in a loop (in contrast to pop_ProcessSet). This function is designed to be used at the command line (or by GUI) after primary processing is complete. It is only implemented for a subset of pop functions that are useful after primary processing at the command line. For example, ScoreERP will likely be called many times as you consider various windows and scoring methods. Similarly LoadFig and ViewRejects are intended to be used after primary processing to check the validity of that processing. It is expected that additional necessary parameters will be passed to the pop function via the use of the OptParams parameter in pop_MultiSet(). The functions that are implemented along with the parameters that need to be supplied via OptParams is provided in the help for this function (type help pop_MultiSet at command line).


As noted earlier, the specific pop function will generally be applied to all Reduced but not Rejected subjects in the P file. ExportNotes and AppendNotes are exceptions that will include Rejected subjects to the degree that notes exist for them.


USAGE: [P] = pop_MultiSet(P, Function, ssFileIndex, OptParams) Command line calls to pop_MultiSet() provide a standard interface to apply many pop functions to all subjects in a P file. It requires you to input only (up to) four simple parameters at the command line. They are defined as follows:

INPUT PARAMETERS P: A Parameter (P) file

Function: A character string that matches the name of a pop function without the 'pop_' and the '()'. It is case sensitive and should use TitleCase

ssFileIndex: This is the index of the ssFile field in the P file with the name of the EEG file required to execute this pop function. It is not necessary for all pop functions as some (e.g., LoadFig) do not require an EEG file

OptParams: This is a cell array that allows input of any additional parameters needed by the pop function. As a cell aray, it is quite flexible and entries in this cell array can take varied forms (double, char, cell). See help for pop_MultiSet() for details on the requirements for any specific pop function that is implemented


OUTPUT PARAMETERS P: an updated (possibly) P file. Currently, none of these functions update P but it is included for consistency and use in scripting.


Examples of typical/useful pop_MultiSet() calls are provided at the bottom (commented out) of each demo script.

Sample PhysBox Processing Scripts, Parameter Files, and Data

Demonstration Sets by Measure

Startle: Zip file
ERP: Zip file
Corrugator (time domain): Zip file
Skin Conductance Response: Zip file

Checking Data Reduction Integrity

Checking Event Table Structure

pop_EventCheck()

Via Script

Demo EEGlab/Matlab script for checking event code count, timing/spacing and counterbalancing: CheckEventCodes.m

Check Startle Data Reduction

pop_CheckStartle()

Check ERP Data Reduction

pop_CheckERP()


LoadFig

pop_LoadFig() and multiset processing


ViewRejects

pop_ViewRejects() and multiset processing (soon)

PhysBox Functions

list each function here

PhysBox Listserv

To join or leave the PhysBox Listserv, send a blank email from your relevant email account to either:

join-physbox@lists.wisc.edu

leave-physbox@lists.wisc.edu

Citing PhysBox

Cite both PhysBox plugin and EEGLab toolbox

Curtin, J. J. (2011). PhysBox: The Psychophysiology toolbox. An open source toolbox for psychophysiological data reduction within EEGLab. http://dionysus.psych.wisc.edu/PhysBox.htm


A Delorme & S Makeig (2004) EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics. Journal of Neuroscience Methods, 134:9-21

For Developers

https://svn.code.sf.net/p/physbox/code/trunk/

svn+ssh://jjccurtin@svn.code.sf.net/p/physbox/code/trunk/

https://sourceforge.net/p/forge/documentation/SVN%20and%20Project%20Upgrades/

download the TortoiseSVN pdf

Dialog Box GUI Examples

To Do and Future Functionality

To Do

  • Need help for pop_DiagnosticFigure
  • AppendNotes has bug when new note is added that is shorter than previous note for same subject, it will not erase all of previous note.
  • AvgFigure should take and (optional) parameter which lists events to plot
  • Check on NaNs for subjects with no epochs in SAFE. Why are fields in sets earlier then EPHFin NaN?
  • Make the method input parameter of ScoreERP a cell array, rather than a string. It would be fun if we had the option to specify unique scoring methods for each of our windows. perhaps the current setup (ie, single method) could be the default if only one method were passed?
  • Demo script and Parameter file for CRG (time and frequency) and SCR
  • Save vs. Saveas in GUI
  • Create notes_ScoreWindows() and notes_ScoreERP() based on notes_ScoreStartle()
  • Systematic update of COM at end of functions.
  • Systematic completion of help for notes and support functions
  • fix warning message precision error in AdjTime()
  • Figure out how setname is set
  • Create a ReadDat and WriteDat that works with tdfread/write but converts char fields to cell rather than char array.
  • Make sure that MarkMean and MarkThreshold can be called multiple time without overwriting past results. Also update code in MarkMean (and maybe MarkThreshold) to model use of max for identifying rejected trials)
  • Figure out how to speed up pop_AppendNotes
  • make change gain (e.g., for PRB) function for CON files
  • Make all parameter calls like ButterworthFilter with option to include ParameterIndex in fieldname in pop_ProcessSet(). Definitely need ParameterIndex for ScoreERP and Score Windows
  • Warning for ExportScores function if subID is in file already. Maybe save in notes like agWarning?
  • Add LoadSet to pop_ProcessSet for later call in script to loading set files that arent currently in the processing stream
  • Write help menu for function with links as per eeglab
  • ExportScores takes list of scores
  • Figure out when to use eeg_hist and eegh. Generally consider what COMs to record. Possibly Add new COM field for multiset?
  • Need pop_ScoreLatency() for ERP
  • Need pop wrapper for pop_image()
  • Need wrapper for pop_rejepoch (already in menu)
  • Need wrapper for pop_select (need in Menu)
  • Make pop_Convert2set()
  • Finish pop_CheckERP()
  • Consider what happens to notes fields when EEG= emptyset for functions like pop_CreateAvg and pop_AverageWaveform. If this is a second (or later) reduction, with the old notes remain?

Possible Future Functionality

  • Consider ways to mark bad trials and review visually with independent reviewers in PhysBox GUI
  • consider added a field in output file and notes output for mean in 150-250 for startle. It would be very similar to basedeflect scoring currently.
  • need a REMOVE SCORES function to get rid of ERP scores from scores field that don’t work.
  • write a Parameter file creating script. This can actually be a pop_function that takes STL or ERP and creates a shell (header) with typical columns for default reduction
  • Explore new toolbox for viewing data. Consider including as alternative view option

http://www.frontiersin.org/neuroinformatics/10.3389/fninf.2012.00017/abstract?utm_source=newsletter&utm_medium=email&utm_campaign=Neuroscience-w28-2012 http://visual.cs.utsa.edu/research/projects/eegvis

  • Estimate missing data for STL
  • reject based on point by point exceeding SDs from mean (i.e., confidence envelope around full trial)
  • Check for each parameter in sub functions and output descriptive error when not found
  • Need better DiagnosticFigure for ERP
  • Think more carefully about eeg_FastFourier. Compare to pwelch, etc
  • Function to find peak latency of components (in various windows) in grand average to use in selection of scoring windows.
  • better screen processing info for EventRecode. Include what is being recoded to what