User Reference:BCI2000Analysis

From BCI2000 Wiki
Jump to navigation Jump to search


The BCI2000Analysis program is a universal tool for

  • Applying Signal Processing filters to existing data,
  • Testing and Benchmarking new Signal Processing filters,
  • Training and testing Linear Classifier weights using various methods.

The program may be viewed as a more versatile version of the BCI2000 Offline Analysis tool, and a complement of the P300Classifier tool. Unlike BCI2000 Offline Analysis, it does not require Matlab to run. Unlike the P300Classifier tool, it allows to use classifier training methods other than SWLDA, and to visualize time courses and topographic plots of P300 responses. While it displays classification results in numerical form, it does not translate classifications into spelling results, though.

The BCI2000Analysis main window

The main window consists of areas for training and testing data, a pane containing the filter graph, and a log area that holds log information produced by filters (if any). In the lower left, two condition fields exist to hold the conditions for collecting data into either of two sets that may then be used to train a classifier.

BCI2000Analysis MainWindow.png

Clicking the “Add analysis files” or the “+” button below the analysis files field will open a file dialog that allows you to choose BCI2000 data files for analysis. Similarly, “Add testing files” or the “+” button below the testing files field will allow you to add BCI2000 data files for testing after a classifier has been trained. Analysis and testing files are tested for consistency when added.

By default, the filter graph is automatically populated when one or more training data files are added to the list, and so are the condition fields. If necessary, filter graph and conditions may be edited to fit special needs (see below).

Above the condition fields, a button will show the standard BCI2000 filter configuration dialog when clicked. By default, filter configuration is taken from the first data file in the “training data files” list.

Editing the Filter Graph

By default, a suitable filter graph is automatically chosen when specifying a data file. Still, you may edit such a default graph, choose a different one from the Analysis→FilterGraph menu, or build one from scratch by selecting Analysis→FilterGraph→User defined.

As it suits the BCI2000 model, a filter graph will always begin with a single Source node, and end in a single Application node. In between, filtering may be split into multiple branches but must finally be joined into a single node. By the way filter graph editing works, it is not possible to produce invalid graphs. Whenever you insert a splitter node, a corresponding joint is automatically inserted for you. You may add and remove filters into and from the new branches but when you remove a splitter, all its branches and its joint node are removed.

You insert a filter between two nodes by right-clicking the connection between them, and choosing “Filter…” from the popup menu. A dialog window appears that contains a menu with all pre-existing types of filters, so you may select e.g. “SpatialFilter”, “P3TemporalFilter”, and so on. As a special entry, the list contains “Filter from DLL…” which allows you to choose a BCI2000 filter DLL. This is especially useful when developing a filter that is not part of the standard set of BCI2000 filters.

A special role plays the LinearClassifier filter, which is displayed in red. At its location, data is collected according to the conditions specified in the “Analysis conditions” field. When performing classifier training (see below), this data is then used to train the classifier, and training results are applied to test the classifier.

From the “File” menu, filter graphs may be saved and loaded to and from human readable .bcigraph files. Also, filter graphs may written into C++ PipeDefinition.cpp files suitable for use as a signal processing module’s pipe definition file.

Performing Analysis

You perform an analysis by pressing “Run analysis…” in the button bar, or by selecting “Run analysis…” from the “Analysis” menu. During analysis, a progress bar is displayed. Once done, a new window opens up, showing an r^2 plot. Depending on the input of the LinearClassifier filter, the x axis displays either time in milliseconds, or frequency in Hertz, whereas channels are numbered on the y axis. This is the same plot as displayed by the Offline Analysis tool, and shows the squared correlation between features and conditions at the input of the LinearClassifier filter.

BCI2000Analysis AnalysisWindow.png

In the r^2 plot, you may view an individual value by clicking its location, which will make a tooltip appear. Right-clicking a location in the plot will turn up a context menu offering to view a cross-section across channels (topographic plot), or a cross-section across frequencies/time points (curve plot). You may also manually enter the frequency/time point, or channel, in question by selecting the appropriate entry from the “View” menu.

BCI2000Analysis ERDDistribution.png BCI2000Analysis ERDCurves.png

Using the Profiler

If you press the “Profiler” button in the button bar, or enable the “Profiler” checkbox in the “Analysis” menu, the behavior of “Run Analysis” will change. It will still run the specified data through the pipeline, but it will not produce an r^2 graph as a result. Rather, it will open a window that shows how much time a filter has been using, in terms of a sample block size. If any of these numbers approaches 1, this will be problematic for real-time operation, and the respective lines will be shown in red.

BCI2000Analysis Profiler.png

Training a Classifier

The analysis window provides controls that allow you to train a linear classifier using three distinct methods: Linear Discriminant Analysis (LDA), Step-Wise Linear Discriminant Analysis (SWLDA), and Support Vector Machine (SVM).

For all training algorithms, a downsampling factor may be chosen. For P300 data sampled at 250Hz, this would typically be 10; for ERD data, no downsampling would be appropriate (downsampling factor of 1). Note that downsampling will typically improve classifier performance because it reduces the dimensionality of the classifier, and results in a better ratio of sampled data to degrees of freedom in the classifier.

For the SWLDA training algorithm, three additional parameters are available. p_enter is the p-value for which a feature will be included in classification, p_remove is the p-value for which a feature will be removed from classification. max_iterations limits the number of iterations to perform. Typically, default values are fine.

Once a classifier has been trained, a window appears which shows classifier information on the left side, and a classifier plot on the right side. The classifier plot is similar to the r^2 plot but shows absolute values of classifier weights to give an impression which features are weighted strongly by the classifier.

BCI2000Analysis ClassifierWindow.png

On the left, the classifier’s offset and variance are displayed, plus its performance on training and test data. Note that performance on training data is typically much better than on test data, which is due to overfitting of the classifier. Only the performance on test data should be taken as an indication how well the classifier will perform on unseen data. Performance is shown in % of correct classifications, for both the “normalized” and “raw” case. The difference is that the “normalized” case takes the bias due to unequal number of data samples in the two data sets into account. If the number of data samples in the two data sets agree, “normalized” and “raw” performance will agree as well.

Saving a Classifier as Parameter File

From the classifier window, choose File→Save Classifier Parameters… in order to save a parameter file with only the LinearClassifier parameter. You can then load this parameter file into BCI2000 using the Operator’s Config dialog, or the Load Parameter File scripting command. Similarly, you may save all parameters from the current analysis chain, including LinearClassifier, by choosing File→Save All Filter Parameters… If you want to apply the LinearClassifier to the chain without saving it to a file, choose File→Apply Classifier Parameters.

See also

User Reference:BCI2000Viewer, User Reference:BCI2000FileInfo, User Reference:BCI2000 Offline Analysis, User Reference:P300Classifier