P300 GUI Guide

From BCI2000 Wiki
Jump to: navigation, search

Note

This page talks about the Matlab-based P300GUI tool, which is now outdated, as of BCI2000 v3.0. It is still available at http://www.bci2000.org/svn/tags/BCI2000.v2.1/src/contrib/Tools/P300GUI but is no longer under development. It has been superseded by the standalone P300Classifier tool, which is part of the BCI2000 core distribution. There are minor differences between the two user interfaces.

Introduction

The P300 GUI (Graphical User Interface) can be used to train and test a linear classifier for detection of evoked potentials collected with BCI2000[6] and visualize the waveforms and classification results. It is designed for analysis of BCI2000 data collected using the P3Speller or P3AV paradigms. The program generates feature weights derived via various regression techniques. The specifics of the feature space and training routine can be manipulated using the GUI. The feature weights derived by the GUI can be saved and imported into BCI2000 as a parameter file fragment for online testing.

The GUI is capable of performing several functions independently:

  • Classifier Training: generates feature weights from BCI2000 P3Speller or P3AV data files (classifier weights can be saved and imported into BCI2000)
  • Classifier Testing: applies current or previously created feature weights to BCI2000 P3Speller or P3AV data files and compares the results
  • Visualizing evoked potentials from BCI2000 P3Speller or P3AV data files

The details and operation of each of these functions are described subsequently.


Using the GUI

Getting Started

System Requirements

  • MatLab 7 with the Statistics Toolbox and 1 GB of RAM is recommended

To Launch GUI

  1. Open Matlab and select the path containing the P300_GUI code.
    Launch GUI.png
  2. From the Matlab command window, type P300_GUI and press Enter. The P300_GUI control panel will appear.


The GUI Control Panel

Figure 1: The GUI Control Panel
[#'s] correspond to subsequent descriptions of function


Training Data Pane

[1] Select Training Data Button Use this button to load BCI2000 data files for training. The information for the selected files will appear below the button.
[2] Regression Method Selects the regression method used to derive feature weights. Select from SWLDA (Stepwise Linear Discriminant Analysis), Ordinary Least Squares Regression, and Logistic Regression.
[3] Resp. Window Used to specify the begin and end time points in milliseconds (ms) following the stimuli collected for the analysis. This automatically converted into samples according to the sampling rate of the data (rounded). Only a single data window can be entered and will be evaluated. Negative values are accepted and begin < end.
[4] % random sample Used to train on a sub-sample of the responses randomly selected from the training data. The default (100%) uses all of the data for training.
[5] Spatial Filter Pull-Down Menu Selects the spatial filter applied to the training data. Select 'RAW & CAR', 'RAW only', or 'CAR only' from the drop-down menu. RAW is no spatial filter applied to the data and CAR is a common average reference filter using all of the channels contained in the data file (not just the channels specified in the GUI channel set!!!). The RAW & CAR option will evaluate both types simultaneously for comparison purposes.
[6] Decimation Frequencies Used to specify the temporal decimation frequency of the data in Hz. Multiple values can be entered for simultaneous evaluation and comparison. Set to the sampling rate for no decimation. The lower the Decimation Frequency, the less original data retained for processing.
[7] Max model features Used to specify the maximum number of features to be kept in the SWLDA model (has no effect on the LG or LS regression options). Only a single value can be entered for evaluation.
[8] Channel Set 1 Used to specify the primary channel set that will be used to create feature weights. The specified channels must be a subset of the channels contained in the training data file.
[9] Channel Set 2 Used to specify a secondary channel set to evaluate simultaneously for comparison purposes. The specified channels must be a subset of the channels contained in the training data file. Can be enabled by clicking the check-box.
[10] Create Spreadsheet enable Used to create a Microsoft Excel spreadsheet that summarizes the classification results. Can be enabled by clicking the check-box. If enabled, a spreadsheet having the same name as the training set will be created in the directory of the training files. The results of the training classification will be located in the worksheet having the same name of the training set within the file. If no training file is used, the spreadsheet will use the name and location of the first test file. The results in the spreadsheet will be overwritten if an analysis is performed again using data from the same training set, therefore the spreadsheet should be manually renamed after analysis is complete to prevent accidental deletion of results.
[11] Generate Weights Use this button to generate the feature weights after properly configuring all of the above parameters. The generated weight file labels will appear in the MUD Files Pane and the classification results will appear in the Matlab command window and as figures.
[12] Create R2 Plots Use this button to visualize the training data. This can be performed independently of the weight generation.


Feature Weights Pane

MUD is BCI2000’s moniker for the feature weight matrix. As illustrated in Figure 1, *.mud files appear in the MUD Files Pane, numbered in order of simulation and having the following identifier: ‘ChS1CAR0DF20RS100SW’, where ChS1 indicates Channel Set 1, the value following CAR indicates whether a common average reference was used (0 no CAR used, 1 CAR used), the value following DF indicates the decimation factor, value following RS indicates the random sample value, and the final two characters indicate the regression method (SW: SWLDA, LS: least squares, or LG: logistic).

[13] Add *.mud Files Button Use this button to load previously saved *.mud files. The information for the selected files will appear below the button.
[14] Clear All *.mud files Button Clears all feature weight (MUD) files currently stored in the GUI (those listed in the Feature Weights Pane). This does not delete previously saved *.mud or *.prm files.
[15] File prefix Appends the specified prefix to the feature weight files when saved as a *.mud or *.prm for identification purposes.
[16] File #’s to Save Used to specify the feature weight files to save according to those currently listed in the Feature Weights Pane. Multiple values can be entered that must be a subset of the currently listed of the feature weight files.
[17] Save *.mud Button Generates *.mud files of the selected File #’s to Save in the training data directory. The file name contains the selected prefix and assigned identifier. The *.mud files are used solely for the purposes of the GUI to evaluate feature weights generated from prior sessions in the GUI.
[18] Save *.prm Button Generates *.prm files of the selected File #’s to Save in the training data directory. The file name contains the selected prefix and assigned identifier. The *.prm files are BCI2000 parameter file fragments that can be imported into BCI2000 for online testing of the feature weights (see BCI2000 documentation for details). Important: Only the BCI2000 parameters regarding the MUD weights, channels, and spatial filter are changed when the *.prm fragment is imported into BCI2000, be sure to verify the BCI2000 parameters before conducting an online session!!!


Test Data Pane

[19] Add Test files Button Use this button to load BCI2000 data files for testing of the feature weights. Multiple groupings of test files can be added for comparison. 'Important: If you select several test files, the resulting curves will be averaged over the number of all datapoints. You arrive only at an classification metric for the whole set.'
[20] Clear All Test files Button Clears all test files currently stored in the GUI (those listed in the Test Data Pane). This does not delete the actual data files.
[21] Apply Weights Use this button to test the classification accuracy of each of the MUD files on each of the test files currently stored in the GUI. The classification results will appear in the Matlab command window and as figures.


Status Window

[22] Messages and current status of the GUI are displayed in this window.

Training a Classifier

The ' Training Data ' panel on the left of the GUI contains all of the parameters for generating SWLDA classifier weights from BCI2000 data files.

To generate SWLDA weights:

  1. Press the ’Select Training Data[1] button in the ’Training Data’ panel.
  2. From the dialog box, select the desired BCI2000 P300 *.dat file(s) for training.
    Notes
    • Selected files can be from different sessions of the same paradigm but must contain consistent parameters for proper execution and classification results. If the parameters are not consistent, Matlab may report an error during classification but the generated weights are likely still valid and can be tested because they are merely based on target/standard responses, not the characteristics of the stimuli.
    • Files can only be selected from a single directory, the desired training files should be organized into the same directory prior to using this function.
  3. After all of the parameters are set as desired (see The GUI Control Panel section for details), press the ’Generate Feature Weights[11] button to perform the analysis. For each combination of parameters, the classification results will appear in the command window as they are generated. If the program was unable to generate a useable weight set for the data, this will also be indicated in the command window. When the analysis is completed, each set of MUD weights generated based on the different parameter combinations will appear in the ’MUD files’ pane and plots summarizing the results for each combination of set of MUD weights will appear (see Results Display section).
  4. The training procedure can be repeated multiple times with new MUD weights being appended to the current list in the ’MUD Files’ Pane.
  5. After training is completed and MUD weights are generated, it is recommended to test (cross validate) the MUD weights on independent data before saving. See the Testing a Classifier section for details on testing the MUD weights on independent data files. The weight files can now be saved (see Saving Classifier Weights section for details).


Testing a Classifier

The ’Test Data’ panel on the left of the GUI contains all of the controls for testing currently or previously created MUD weights to one or more BCI2000 test files

To apply weights to test files:

  1. In the ’MUD files’ panel, if no weights have been generated in the current session or additional weights are to be evaluated, press the ’Add *.mud files[13] button to add a single MUD file or generate new weights (see ‘Training a Classifier’ section for details). Repeat until all desired MUD files are loaded. All MUD files must have the same sampling rate and electrode montage. All currently loaded files can be cleared from the current session using the ’Clear All *.mud Files[14] button. Be sure to save any desired unsaved MUD files from a current session before clearing. All of the MUD files listed in the ’Feature Weights’ panel will be applied to the test data.
  2. In the ’Test Data’ panel, press the ’Add Test Data[19] button to add test files. One or more BCI2000 *.dat files can be selected from the same directory as a single 'test file group' each time the button is pressed. Repeat until all desired test file groups are loaded. All files selected should have the same sampling rate and electrode montage as the selected MUD files for valid classification. All currently loaded files can be cleared from the current session using the ’Clear All Test Files[20] button. All of the MUD files listed in the ’MUD files’ panel will be applied to each ’test file group’ listed in the 'Test Data' panel.
  3. After all of the MUD and test files are selected, press the ’Apply Weights[21] button to perform the analysis. For each combination of MUD and test file groups, the classification results will appear in the command window as they are generated. When the analysis is completed, plots summarizing the results for each test set will appear (see Results Display section).
  4. After evaluating the classification results, weight files from the current session can now be saved (see Saving Classifier Weights section for details).



Results Display

The results of all training and test simulations will be displayed in the Matlab command window and as individual performance plots as shown below. The command window (left) displays the predicted character at each intensification sequence for the corresponding feature weights as labeled. The performance curves for each set of feature weights are plotted in individual windows (right). The top and bottom figures in these windows indicate the same results with different plot styles. For test data, an additional plot will be displayed that gives the average of all the individual test data sets selected.

GUI Results.png



Saving Classifier Weights

The ’Feature Weights’ panel on the left of the GUI contains all of the controls for saving selected feature weights listed in the current pane for future use. The weights can be save as either *.mud or *.prm:

  • .mud files are used solely for the purposes of the GUI to evaluate feature weights generated from prior sessions in the GUI.
  • .prm files are BCI2000 parameter file fragments that can be imported into BCI2000 for online testing of the feature weights. Important: Only the BCI2000 parameters regarding the MUD weights, channels, and spatial filter are changed when the *.prm fragment is imported into BCI2000, be sure to verify the BCI2000 parameters before conducting an online session!!! The specific parameters that are updated in the fragment are: MUD (feature weights), NumSamplesInERP(length of classified response in samples), SoftwareCh(# of total recording channels), SpatialFilteredChannels(channels that are included in the spatial filter), SpatialFilterKernel(weights for the spatial filter channels), and TransmitChList(channels that are used for classification).

Note: *prm files can be generated from *.mud files but *.mud file cannot be generated from *.prm files. It is recommended to save *.mud in addition to the *.prm for future analysis.

To save one or more of the current feature weight files as a *.mud or *.prm file:

  1. Enter a prefix that will be appended to the MUD files (for identification purposes) in the ‘File Prefix[15] window.
  2. Enter the corresponding MUD file number(s) of the selected files in the ‘File #'s to Save[16] window and press Enter.
  3. Press the ‘Save *.mud[17] or ‘Save *.prm[18] button depending on the desired file type. The selected MUD files will be saved in the training data directory with a *.mud or a *.prm extension for later use. The files can be identified later by the name, for example, SessionA_ChS1CAR0DF20BPF0SW.mud and SessionA_ChS1CAR0DF20BPF0SW.prm In these names, 'SessionA_' is the chosen prefix, ChS1 indicates Channel Set 1, the value following CAR indicates whether a common average reference was used (0 no CAR used, 1 CAR used), the value following DF indicates the decimation factor, value following RS indicates the random sample value, and the final two characters indicate the regression method (SW: SWLDA, LS: least squares, or LG: logistic).
  4. See the BCI2000 documentation for instructions on how to load a *.prm fragment into a BCI2000 P3Speller or P3AV parameter file.


Visualizing data

Topographies, waveforms, and r2 plots can be generated independently of the other functions using the GUI as follows:

  1. Press the ‘Select Training Data[1] button in the ‘Training Data‘ panel.
  2. From the dialog box, select the desired BCI2000 *.dat file(s) for visualizing.
    Notes
    • Default 16, 32, and 64 channel montages are provided. The electrode montage files (eloc*.txt - see EEGLab [1]) may need to be edited to match different montages.
    • Selected files can be from different sessions, but must use the same electrode montage and sampling rate to produce valid plots.
    • Files can only be selected from a single directory, the desired files should be organized into the same directory prior to using this function.
  3. Select the desired window size [3] and spatial filter [5] from the drop-down menu in the ‘Training Data‘ panel. The ‘Raw & CAR‘ option will visualize the RAW data only! The other options will not effect the visualization.
  4. Press the ‘Create R^2 Plots[12] button. When the processing is complete, an interactive figure will appear displaying the R^2 of the channels verses time (see bottom left). Left-click on the figure to display a plot of the waveform and topography at the specified channel/time location (see bottom right). Repeat to generate additional plots and right-click to finish and exit the interactive plotting mode.

Visualizing the Data.png


Troubleshooting

Verify that you are using the latest release of the GUI (indicated at the bottom left-hand corner of the GUI control panel).

Errors are likely caused by inconsistent or corrupted data files. The GUI does not check all data file parameters for consistency or automatically adjust the default training parameters to the input data. Try to use data files from the same paradigm and configuration when possible.

For other difficulties, it is recommended to restart Matlab.


References

  1. Delorme A, Makeig S. EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics, Journal of Neuroscience Methods 134:9-21, 2004.
  2. Draper N, and Smith H. Applied Regression Analysis, 2nd edition, John Wiley and Sons, 1981, pp. 307-312.
  3. Farwell LA, Donchin E. Talking off the top of your head: Toward a mental prosthesis utilizing event-related brain potentials. Electroenceph clin Neurophysiol 1988; 70: 510-23.
  4. Krusienski DJ, Sellers EW, McFarland DJ, Vaughan TM, Wolpaw JR. Toward Enhanced P300 Speller Performance, Journal of Neuroscience Methods, 167:15-21, 2008.
  5. Krusienski DJ, Sellers EW, Cabestaing F, Bayoudh S, McFarland DJ, Vaughan TM, Wolpaw JR. A Comparison of Classification Techniques for the P300 Speller, Journal of Neural Engineering, 3:299-305, 2006.
  6. Schalk G, McFarland DJ, Hinterberger T, Birbaumer N, Wolpaw JR. BCI2000: A general-purpose brain-computer interface (BCI) system. IEEE Trans Biomed Eng 2004; 51: 1034-43.
  7. Sellers EW, Donchin E. A P300-based brain-computer interface: Initial tests by ALS patients. Clin Neurophysiol: in press.
  8. Sharbrough F, Chatrian, CE, Lesser RP, Luders H, Nuwer M, and Picton TW. "American Electroencephalographic Society guidelines for standard electrode position nomenclature," J. Clin. Neurophysiol., vol. 8, pp. 200-202, 1991.


Release Notes

V2.0 09/30/05

Original Release

V2.01 11/07/05

Added 8 channel P300 montage

V2.02 12/15/05

Now able to plot averages with unequal numbers of sequences for testing
Added channel number checks

V2.03 12/21/05

Changed to standard default analysis settings
Made compatible with floating point (32) data

V2.04 12/23/05

Added warning for unequal train and test sampling rates
Corrected target definition to be printed character
Added classification of spaces (_) and printing of backspaces (<)
Updated to read latest BCI2000 header

V2.05 02/13/06

Now compatible with new target definition matrix

V2.051 02/17/06

Added fix for German characters - umlaut characters classified as standard characters

V2.052 02/21/06

Made data loading more memory efficient

V2.06 02/22/06

Added variable response window start point
Implemented new function to load BCI2000 data
Resized plot windows

V2.061 03/14/06

Corrected classification for non-square matrices
Changed to save MUD prior to training classification

V2.07 03/15/06

Created a button to generate and save a BCI2000 parameter file fragment based on the selected MUD matrix

V2.08 03/30/06

Added Least Squares and Logistic Regression options
Fixed problem with *.prm Software Chs.
Removed MA window from interface (now uses same values as DF)

V2.09 04/12/06

Changed to compare row/column results rather than “Text to Spell’
Encoded Online (“Free spelling”) data, assuming that the selected character is the target.

BCI2000 v2.0 Release

02/06/08

Updated to be compatible and fully functional with BCI2000 v2.0 P3Speller data, and backward compatible with previous versions. This version has not been verified with P3AV data.
Symbol rate figure replaces the percent correct ribbon figure.
Fixed CAR filter generation.

Contact/Credit

Dean Krusienski
Assistant Professor
Electrical Engineering
University of North Florida
email: deankrusienski@ieee.org