User Reference:P300Classifier

From BCI2000 Wiki
Jump to navigation Jump to search

Synopsis

The P300 Classifier GUI (Graphical User Interface) is a tool that allows to train and test a linear classifier for detection of evoked related potentials collected with BCI2000. This GUI is designed for the analysis of BCI2000 data collected using the P3Speller or Stimuli Presentation paradigms. The program generates feature weights by using a linear classifier algorithm called Stepwise Linear Discriminant Analysis (SWLDA). The specifics of the feature space and training routine can be manipulated using the GUI. The feature weights derived from the GUI can be saved and imported into BCI2000 as a parameter file fragment (*.prm) for online testing. Unlike the Matlab-based P300 GUI, the P300 Classifier GUI has the main advantage of being completely Matlab independent. All its core functionality is written in C++ accompanied with a friendly graphical user interface written in Qt. Additionally, this new tool is completely scriptable; that is the investigator can write all the commands needed to train and test the linear classifier in a batch file without using the GUI. The P300 Classifier GUI provides the following functionality to investigators:

Classifier Training
Generates feature weights from BCI2000 P3Speller or Stimuli Presentation data files
Classifier Testing
Applies current feature weights to BCI2000 P3Speller or Stimuli Presentation data files and compares the results

Location

http://www.bci2000.org/svn/trunk/src/core/Tools/P300Classifier

Versioning

Author

Cristhian Mauricio Potes

e-mail

cmpotes@miners.utep.edu

Source Code Revisions

  • Initial development: May 15, 2009
  • Tested under: Windows XP, Windows Vista
  • Known to compile under: Visual Studio 2008
  • Broken since: --

Control Panel

The P300 Classifier GUI is composed of three panes: Data, Parameters, and Details.

Data Pane

Data Pane allows the user to

  • Load training and testing data files and an INI file
  • Generate and apply feature weights
  • Write a parameter file fragment (*.prm)
Data pane


  • [1] Load Training Data Files: Use this button to load BCI2000 data files for classifier training. The information for the selected files will appear at the top of the button.
  • [2] Load Testing Data Files: Use this button to load BCI2000 data files for classifier testing. The information for the selected files will appear at the top of the button. Training and testing data files must be compatible.
  • [3] Load Ini File: Use this button to load an INI file with all the parameters needed for the classifier.
[Initialization]

maxiter = 60 // to set Max Model Features
penter = 0.1000 // to set Penter
premove = 0.1500 // to set Premove
spatial_filter = 1 // to set Spatial Filter. Set 1 for RAW and 2 for CAR
decimation_frequency_Hz = 20 // to set Decimation Frequency
channel_set = 1 2 3 4 5 6 7 8 // to set Channel Set
Resp_window_ms = 0 800 // to set Response Window. The response window must be in milliseconds (ms) 
  • [4] Generate Feature Weights: Use this button to generate the feature weights after properly configuring all of the parameters in the Parameters pane. This button will be enable only if the parameters are properly configured and there exists training data files. Once it has been generated feature weights properly, a suggested name for the parameter file fragment (*.prm) will show up at the top of the Write *.prm File button.
  • [5] Apply Feature Weights: Use this button to test the classification accuracy of the feature weights currently stored in the GUI. The classification results will appear in the Details pane.
  • [6] Write *.prm File: Use this button to save the parameter file fragment with the name suggested at the top of this button. The *.prm file is a BCI2000 parameter file fragment that can be imported into BCI2000 for online testing of the feature weights.

Parameters Pane

Parameters Pane contains all the parameters needed to generate feature weights by using the SWLDA algorithm. These parameters can be loaded using the Data Pane button. If the parameters are properly configured the Generate Feature Weights button is enabled.

Parameters pane
  • [7] Max Model Features: Used to specify the maximum number of features to be kept in the SWLDA algorithm. Only a single value can be entered for evaluation. The default value is 60.
  • [8] Penter: Used to specify the maximum p-value for a variable to be entered. The default value is 0.1000. Penter must be less than Premove and 0<Penter<1. Only a single value can be entered for evaluation.
  • [9] Premove: Used to specify the maximum p-value for a variable to be removed. The default value is 0.1500. Premove must be greater than Penter and 0<Premove<1. Only a single value can be entered for evaluation.
  • [10] Spatial Filter: Selects the spatial filter applied to the training data. Select RAW or CAR 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 default spatial filter is RAW.
  • [11] Decimation Frequency: Used to specify the temporal decimation frequency of the data in Hz. Only a single value can be entered for evaluation. Set this parameter to the Sampling Rate value for no decimation. The lower the Decimation Frequency, the less original data retained for processing. Typically, 20 is a good choice for this parameter.
  • [12] Channel Set: Used to specify the 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.
  • [13] Response Window: Used to specify the Begin and End time points in milliseconds (ms) following the stimuli collected for the analysis. These two values are 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. Begin must be less than End.

Details Pane

Details Pane displays information about the BCI2000 training data files and the classification results.

Details pane
  • [14] Sampling Rate: Displays the sampling rate in (Hz) contained in the training data files.
  • [15] Number of Channels: Displays the total number of channels contained in the training data files.
  • [16] Classifier: Displays the classifier applied to generate the feature weights. The P300Classifier GUI only uses the SWLDA classifier algorithm.
  • [17] Application: Displays the type of application used for the investigator. The application can be either P3SpellerTask or StimulusPresentationTask.
  • [18] Interpret Mode: Displays the interpret mode used for the investigator. The mode can be either Copy Mode or Online Free Mode.
  • [19] Duration: Displays the duration in seconds (s) of the whole training data files.
  • [20] The text editor displays the classification results for the training and testing data files.

Batch Scripting

The P300 Classifier Tool can be scripted in a batch file using the example format below:

C:\BCI2000.x64\tools\P300Classifier\P300Classifier.exe -TrainingDataFiles C:\BCI2000.x64\data\ClassifierTest001\ClassifierTestS001R01.dat -inicfg C:\BCI2000.x64\tools\P300Classifier\parameters.ini -ClassifierOutputFile C:\BCI2000.x64\data\ClassifierTest001\P3Classifier_ChS1_RAW_SW.prm

Methodology

Methodology Concept

The idea behind the P300Classifier is to train and test a linear classifier (SWLDA) for detection of evoked potentials collected from brain signals. This is achieved in the following steps:

  • Training Data Files
  1. Load BCI2000 data files
  2. Get P300 responses
  3. Generate feature weights for a linear model using SWLDA
  4. Apply linear classifier to get scores
  5. Interpret scores according to the given application
  • Testing Data Files
  1. Load BCI2000 data files
  2. Get P300 responses
  3. Apply linear classifier to get scores
  4. Interpret scores according to the given application

Methodology Step By Step

Step 1: Load BCI2000 Data Files

The first step to start using the P300Classifier GUI is to load training and testing BCI2000 data files specified by the investigator. The BCI2000 data files are checked for compatibility and consistency. If all training data files are valid then the Generate Feature Weights button is enabled and each file is colored with light green. Otherwise, the Generate Feature Weights button is not enabled, and each file is colored either with yellow or pink. See the following color coded scheme and example.

  • files ok : The files are valid.
  • files mismatch : The files may be valid but there is a mismatch with another file.
  • files error : The files are invalid.
Training data file is not valid; the file is highlighted in pink. Testing data file is valid; the file is highlighted in light green. The Generate Feature Weights button is not enabled until the training data file is valid.

Step 2: Get P300 Responses

Signals, states, and parameters are extracted from BCI2000 training and testing data files. However, the signals that are only extracted for analysis are those defined by the user in the Response Window. Only these signals are filtered and downsampled. The filter employed is a Moving Average (MA) Filter implemented as a Direct form II Transposed. The MA filter belongs to the FIR filter and works as a low pass filter removing high frequency components of the signal.

Step 3: Generate Feature Weights for a Linear Model using Stepwise Linear Discriminant Analysis (SWLDA)

The idea behind SWLDA is to obtain a final linear model that approximately fits a set of data (stimulus) by using multiple linear regressions and iterative statistical procedures, thus selecting only significant variables that are included in the final regression.

The SWLDA algorithm can be summarized in the following steps:

  • STEP 1: Compute the autocorrelation matrix to select the variable most highly correlated to the observations. The selected variable is included in the linear model.
  • STEP 2: Fit an initial model by performing a linear regression equation with the included variable using least squares.
  • STEP 3: Check if the variable added is that one which makes greatest improvements in "goodness of fit." That is, remove the added variable if its variance contribution in the regression is insignificant at a specified F level (F-test). If the added variable is removed go to Step 5, else go to Step 4.
  • STEP 4: Add the variable to the model if there is a significant variance reduction at a specified F-level.
  • STEP 5: Remove the added variable from the correlation matrix. Go to step 1.

The method terminates when no single step improves the model.

Step 4: Apply Linear Classifier to Get Scores

Scores are computed based on the variables included in the final linear model and the corresponding feature weights.

Step 5: Interpret Scores

Scores are interpreted according to the given application, which can be either P300SpellerTask or StimulusPresentationTask.

Tutorial

Training the SWLDA Classifier

The Parameters pane contains all of the parameters for generating feature weights from BCI2000 data files.

The investigator must follow the next steps to generate feature weights:

  • Press the Load Training Data Files [1] button in the Data pane.
  • From the dialog box, select the desire BCI2000 *.dat file(s) for training. Selected files can be from different sessions of the same paradigm but must contain consistent parameters. Each training data file is colored according to the color coded scheme explained in Load BCI2000 data files. Files can only be selected from a single directory; the desired training data files should be organized into the same directory prior to using the P300Classifier GUI.
  • Once the Parameters pane is correctly set as desired, the Generate Feature Weights button is enable. Press this button to perform the analysis and generate feature weights. The Overall Progress bar displayed in Data and Details panes will indicate the progress of the SWLDA. The classification results will appear in the text editor [20] of Details pane. Every time it is pressed the Generate Feature Weights button, and the analysis is successfully completed, there is generated a new feature weights set.
  • The training procedure can be repeated multiple times generating a new feature weights set that depends on the configured parameters.
  • After training is completed and feature weights are generated, it is recommended to test (cross validate) the feature weights on independent data (testing data files) before saving the parameter file fragment (*.prm). Additionally, there is a suggested parameter file fragment name displayed on the top of Write *.prm File button, which can be used to save the *.prm file either with the suggested name or the name specified by the investigator.

Testing the SWLDA Classifier

The Data pane contains the Apply Feature Weights [5] button for testing the generated feature weights to one or more BCI2000 testing data files.

The investigator must follow the next steps for applying feature weights to testing data files:

  • Once it has been successfully generated feature weights and there exists testing data files, the Apply Feature Weights button is enabled. If there are no testing data files loaded, the investigator must press this button to load testing data file(s). 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. Selected files can be from different sessions of the same paradigm but must contain consistent parameters. Each testing data file is colored according to the color coded scheme explained in Load BCI2000 data files. All testing files selected should have the same sampling rate and electrode montage as the training data files selected to generate the current feature weights set.
  • After all the testing data files are correctly selected, press the Apply Feature Weights [5] button to perform the analysis. Results of the classification are displayed in the text editor [20] of Details pane. The Overall Progress bar displayed in Data and Details panes will indicate the progress of the classification.
  • After evaluating the classification results, the *.prm file from the current session can be saved by pressing the Write *.prm File button.

Example

In the next example, it is desired to compute feature weights from the following BCI2000 training data file eeg3_1.dat.

By pressing the Load Training Data Files button the file eeg3_1.dat is uploaded as shown in the next figure. Notice that the training data file is set up correctly since it is colored in light green. Remember that the classifier algorithm will be trained by using this training data file.

By pressing the Load Training Data Files button it is uploaded the desired BCI2000 training data file. The classifier algorithm is trained by using this training data file.

The parameters shown in Parameters Pane are set by default. For illustration purposes, however, it is desired to load initial parameters from an INI file called parameters.ini by pressing the Load Ini File button.

[Initialization]
maxiter = 60 
penter = 0.1000 
premove = 0.1500 
spatial_filter = 2 
decimation_frequency_Hz = 20 
channel_set = 1 2 3 4 5 6 7 8 
Resp_window_ms = 0 800 
By pressing the Load Ini File button it is uploaded the desired initial parameters that the classifier algorithm will use to generate the corresponding feature weights.

Once the initial parameters are loaded and properly set up, the Generate Feature Weights button is enabled, and each one of the parameter fields is colored in light green as shown in the next figure.

All of the parameter fields are properly set up. Thus, each parameter field is colored in light green.

The investigator can change any of the parameters fields at any time. However, if that change is not properly set up (i.e., the given parameter is invalid), the corresponding parameter field will be colored in pink.

  • parameter field ok : The parameter is valid.
  • parameter field error : The parameter is invalid.

In the next figure, the investigator changes the Channel Set field introducing one more channel, channel 9. Since this channel is not a subset of the channels contained in the training data file, the corresponding field is colored in pink, and a tool tip is popped up displaying the error message. Additionally, the Generate Feature Weights button is not enabled until that specific field is properly configured.

The Channel Set field is modified by introducing one more channel, channel 9. This field is colored in pink since channel 9 is not a subset of the channels contained in the training data file.

Once the parameters are properly configured, the investigator is ready to generate feature weights by pressing the Generate Feature Weights button. Details of the training data file and progress of the classification are displayed in the Details Pane as shown below.

Details of the training data file and progress of the classification. There is an overall progress bar in both the Data Pane and Details Pane.

Once the classifier has been trained with the BCI2000 training data file, and it has generated the corresponding feature weights, it is desired to test these feature weights with the following BCI2000 testing data file eeg3_2.dat.

By pressing the Load Testing Data Files button this file is uploaded as shown in the next figure. Notice that the testing data file is set up correctly since it is colored in light green. If the testing data file is valid then the Apply Feature Weights button is enabled.

By pressing the Load Testing Data Files button it is uploaded the desired BCI2000 testing data file. The file is colored in light green if valid.

The investigator is ready to apply feature weights by pressing the Apply Feature Weights button. Details of the training data file (no testing data file) and progress of the classification are displayed in the Details Pane as shown below.

Details of the training data file and progress of the classification. Testing feature weights generated from the training data file eeg3_2.dat. There is an overall progress bar in both the Data Pane and Details Pane.

If satisfied with the classification obtained from the current feature weights, the investigator can write a parameter file fragment *.prm with the name suggested in the Write *.prm File field by pressing the Write *.prm File button. The *.prm file is a BCI2000 parameter file fragment that can be imported into BCI2000 for online testing of the feature weights. In the following image, it is written a *.prm file called MUDChS1_RAW_SW.prm.

Write a parameter file fragment *.prm. The *.prm file is a BCI2000 parameter file fragment that can be imported into BCI2000 for online testing of the feature weights.

Every time the investigator changes any of the parameters in the Parameters Pane, the Apply Feature Weights button is disabled. To enable it, the investigator must generate feature weights again.

Future work

  • Present classification results as topographies and graphs as the Matlab-based P300 GUI
  • Let the P300Classifier GUI work with frequency-based features
  • Speed up the P300Classifier GUI by using multithreading when solving the Least Squares (QR factorization)

References

  • N. R. Draper, H. Smith. Applied Regression Analysis. John Wiley & Sons, Inc, New York, 1966.
  • P. M. Embree, B. Kimble. C Language Algorithms for Digital Signal Processing. Prentice Hall, Englewood Cliffs, New Jersey, 1991.
  • A. Ralston, H. S. Wilf. Mathematical Methods for Digital Computers. John Wiley & Sons, Inc, New York, 1962.
  • W. H. Press, S. A. Teukolsky, W. T. Vetterling, B. P. Flannery. Numerical Recipes in C. Cambridge University Press, New York, 1988.