User Tutorial:BCI2000 Tour

From BCI2000 Wiki
Revision as of 14:19, 8 February 2023 by Mellinger (talk | contribs) (→‎Parameter Files)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

The following description is intended to get you started and make you comfortable using BCI2000. It demonstrates the use of BCI2000 without the need for data acquisition hardware. In addition, it will introduce you to some of the most important software components and tools included in the BCI2000 distribution.

Starting up BCI2000

BCI2000 consists of four programs (modules) that need to be started up in a certain order. These modules handle acquisition of brain signals (i.e., Source module), processing of these brain signals (Signal Processing module), user feedback (i.e., User Application module), and the interface to the investigator (i.e., Operator module), respectively. These four modules can be started using the script (batch) files in the batch directory. Alternatively, there is a BCI2000Launcher program that allows you to manage BCI2000 module startup using a graphical user interface.

We will begin this introductory tour by double-clicking the file batch/CursorTask_SignalGenerator.bat. This will launch the modules required for a simulation of a Mu rhythm BCI session.

BCI2000 Help

When the main operator window appears, choose BCI2000 Help from the Help menu. The Operator module's help page will be opened in a web browser window. On the left side of the help page, a navigation menu provides access to available BCI2000 documentation.

The BCI2000 help is a local copy of the BCI2000 online documentation wiki and provides a snapshot that corresponds to your version of the BCI2000 executables.

Parameter Files

The parameters for a particular experiment implemented in BCI2000 are stored in parameter files. Before performing an experiment, you will typically load a parameter file that contains subject-specific as well as general configuration information.

In the main window, click the Config button. A configuration window appears. There, click the Load Parameters button, which will open up a file chooser dialog. Open parms/examples/CursorTask_SignalGenerator.prm.

Entering a Subject ID

BCI2000 stores data files in directories with names that are constructed from subject ID and session number.

In the configuration dialog, go to the Storage tab, and identify the DataDirectory parameter. This parameter determines the path to the top level data directory, i.e., the directory below which session directories will be created. By default, this parameter is set to ../data, a relative path that points to your BCI2000 installation's data directory.

Go to the SubjectName parameter, and enter an ID such as TEST, or your own initials.

Parameter Help

There is a "Help" button on the right side of the configuration window. Click that button, and observe that the mouse cursor turns into a question mark. Move the mouse cursor over the SubjectName parameter label, and press the left mouse button.

A web browser window will open up and show a help page that describes the SubjectName parameter.

Applying Configuration Parameters

Close the configuration dialog by using its close button (the button labeled "X" located on the top right corner of the window). This will accept your parameter changes (there is no "Cancel" option).

In the main window, click Set Config. This will apply the changes in configuration. Specifically, the Operator module sends configuration parameters to the remaining BCI2000 modules. These, in turn, will validate the parameter values to make sure they are appropriate. If all values are appropriate, a signal window will appear that displays simulated EEG. The first time, this window is rather small and is located in the upper left corner of the screen. Please resize and move it to your liking -- its size and position will be preserved across BCI2000 sessions.

In a true BCI session, in which you will be recording signals from the brain, you will use this window to assess the quality of the recorded signals. In this simulation session, you will notice a change in the simulated brain signal when you move your mouse. We will alter use these signal changes to control a cursor on the screen.

When you right-click on the signal window, this will bring up a context menu with particular display options such as increasing/decreasing the number of channels displayed, choosing display colors, applying filters to the signal, etc. (Details are described on the Operator Module's reference page.)

Performing a Session

Once you clicked Set Config, the Start button will be active (assuming all parameters have been validated and accepted). Press "Start" to start a simulated feedback session. During the session, you will see a cursor that moves from the left to the right at a constant rate. You will also see one of two targets highlighted on the right side of the screen. Your task is to move the cursor up or down such that it hits the highlighted target. In simulation mode, you can move this cursor by moving the mouse cursor up and down. In BCI experiments, the subject's task is to use brain signals, rather than the mouse, to move the cursor.

The period during which the cursor moves from left to right is called a trial. During operation, a number of trials will follow each other. Many trials make up one experimental run, where each run usually lasts about 3-5 minutes. When the run is finished, BCI2000 will stop operation on its own, and the Start button will change to Resume. At that time, the corresponding data file has been closed. Clicking Resume each time, you may add as many runs to the current Session as you like. All runs within a session will be stored as separate files in that session's data directory.

BCI2000 contains a component that adapts itself to the brain signal's characteristics (i.e., its mean value and its amount of variation). This component needs to observe the signal for a few trials until it has appropriately adapted to those characteristics. This means that initially you will not feel a correspondence between your actions and the cursor; just stick with it for a few trials, and you will note how control gets more accurate over time. Also, it is important that you place the mouse cursor in a center position at the beginning of each trial, to give you enough space to move into the required direction. Likewise, when a real subject controls the cursor using brain signals, cursor control will only be possible after blindly following instructions for a few trials.

When you have acquired one or more runs, you may quit BCI2000.

Opening Data Files in BCI2000Viewer

Use Windows Explorer to display the contents of data/<SubjectName>001, which is the session directory corresponding to your recorded session (in place of <SubjectName>, enter the ID that you used for the SubjectName parameter). In the session directory, single runs correspond to .dat files carrying the session's name, appended with a run number.

To view the content of a data file, open it in the BCI2000Viewer program provided in tools/BCI2000Viewer. We recommend that you double-click the .dat file in question, and then use "Choose application" to permanently associate BCI2000Viewer with the .dat extension. Alternatively, drag a .dat file (or a link to a .dat file) onto the BCI2000Viewer icon or BCI2000Viewer's application window. This will display the file's contents.

Viewing Event Marker Information

Every BCI2000 contains event marker channels that are stored with every signal sample. To view some of these event markers (which are called state variables in BCI2000), check the "TargetCode", "ResultCode", and "Feedback" checkboxes displayed in the top right corner of its application window once you opened a file in BCI2000Viewer.

The values of these event markers will be displayed on top of the signal traces. Whenever TargetCode changes from 0, a target was displayed during the recording. Whenever ResultCode changes from 0, a target has been hit by the cursor. A Feedback value of 1 indicates that the feedback cursor was visible. In data analysis, this state information allows to determine trial structure and data labels. It is important to note here that the number, names, and nature of the BCI2000 state variables can be easily adapted to fit your needs.

Help on state variables is available as well. Right-click the "TargetCode" entry in the top right corner of the BCI2000Viewer window and choose Help on the "TargetCode" state variable from the context menu. A browser window will open up and will show a help page that describes the TargetCode state variable.

Viewing Parameters using BCI2000FileInfo

In addition to state information, each data file contains the full set of parameters and their values that defined recording of this particular run. You may view those parameters, and save them to a parameter file, in original or modified form, using the BCI2000FileInfo program that is located at tools/BCI2000FileInfo.

To open a .dat file in BCI2000FileInfo, drag-and-drop it onto the program symbol or into the program's main window. Then, click "Show Parameters." This will open a parameter configuration dialog identical to the one you know from the Operator module.

Stimulus Presentation

In addition to the cursor feedback paradigm, BCI2000 comes with a multi-purpose Stimulus Presentation module. This module is able to deliver visual and auditory stimuli in user-defined or pseudo-random sequences, and may respond to input from external devices. Thus, in many situations, it omits the need for dedicated programs like Presentation or e-Prime. In BCI research, the BCI2000 StimulusPresentation module is often used for an initial Mu rhythm session. Still, it has very good timing precision, and thus makes its use suitable for a wide range of psychophysiological experiments such as the ERP experiments described here. In addition, it can be used in conjunction with the P3SignalProcessing module (which can average and classify ERPs) to provide real-time feedback to evoked potentials.

To try the stimulus presentation module, start BCI2000 using the batch/StimulusPresentation_SignalGenerator.bat batch file. Then, click Config, and load the configuration file at parms/examples/StimulusPresentation_SignalGenerator.prm. Go to the Storage tab, and enter a subject ID into the SubjectName parameter. Run the experiment clicking Set Config and Start. (Note: The goal here is simply to introduce you to the stimulus presentation module. We will not show how to modify the stimuli.)

When you are done, locate the resulting data file at data/<SubjectName>001/<SubjectName>S001R01.dat, and open it using BCI2000FileViewer, similar to what you did for the simulated cursor movement session earlier in this tour. In BCI2000FileViewer's main window, check the StimulusCode checkbox to display the StimulusCode state variable. During presentation of a stimulus, the StimulusCode state is set to an ordinal number corresponding to the stimulus. In data analysis, this information may then be used to segment data into epochs, and to group epochs according to stimuli.

P300 Speller

As part of its core distribution, BCI2000 comes with a P300 Speller module. The P300 Speller module implements a BCI that uses evoked responses to select items from a rectangular matrix, as it was originally described by Farwell and Donchin (1988).

To calibrate the P300 Speller for an individual subject, it is operated in a "copy spelling" mode, which prompts the user to pay attention to pre-defined letters in sequence. Start batch/P3Speller_SignalGenerator.bat, click Config, and load parms/examples/P3Speller_CopySpelling.prm. Close the configuration window, then click Set Config and Start to view copy spelling in action.

In simulation mode, the simulated EEG will simulate evoked responses on the respective items, allowing to test signal classification and spelling functionality. Therefore, spelled letters will correspond to predefined letters.

Once calibrated, the purpose of the P300 Speller is to choose arbitrary letters from the matrix, i.e., "free spelling," without a pre-defined letter sequence. The speller also supports multiple matrices (or "menus"), graphical icons, and wave files.

To perform a "free spelling" demo with multiple menus, click Config and load parms/examples/P3Speller_Menus.prm. Then close the configuration window, click Set Config, and Start. In simulation mode, selecting a matrix element is achieved by clicking it with the mouse. Actual P300 classification is done by averaging over a fixed number of epochs, so clicking an item will not immediately select it. Rather, mouse selection will override classification once the number of averaging epochs is reached, which takes a few seconds.

Where to go from here

In this tour, we covered several basic aspects of BCI2000 operation and how to view information contained in data files. Additionally, you have seen the software elements available to build BCIs based on brain signal rhythms and evoked responses.

When you are an experimenter, you might want to go through one of the tutorials that introduce you to actual EEG experiments:

If you are a programmer wishing to modify or extend BCI2000, you should start with

In case you would like to adapt BCI2000 to your own amplifier, you may furter be interested in

If you want to apply your own signal processing to brain signals, see

For further BCI2000 resources that support you in development of Data Acquisition, Signal Processing, or User Application modules, see Rapid Development.

All documentation is accessible through a hierarchy of content pages, starting at the Main Page.

See also

User Reference:Contents, Technical Reference:Contents, Programming Reference:Contents