PsychoPy

PsychoPy is an open-source application used to perform a large number of neuroscience, psychology, and psychophysics experiments. [1] This wiki page first describes the two components that remotely start BCI2000 from PsychoPy. The next section describes the steps to add the new components in the PsychoPy application. The final section goes over two tutorial examples.

Video Overview

Prerequisites

For this project, you will need two things: BCI2000 compiled for your system and the newest version of PsychoPy.

Components

BCI2000Start

This component starts up the BCI2000 modules remotely. The component takes two parameters:

Path: Path to the BCI2000 prog directory, which contains the BCI2000Remote.py file.
States: List of new states to add to BCI2000. The states in the list are defined as follows: 'StateName defaultValue maxValue.' Eg: lastKey 0 255, correctKey 0 1.

NOTE: You can specify the modules with which you want to run the experiment with the BCI.StartupModules command in the Init.py file previously copied into your PsychoPy environment. You can also specify which parameters to use for the experiment and specify other command-line arguments with the BCI.LoadParameterRemote command.

BCI2000UpdateEvent

Note: It is highly recommended to use EVENTS instead of STATES when recording experimental values using BCI2000. This is because the timing of events is on a per-sample basis, while states are recorded on a per-block basis. The time of recorded states can be delayed by up to a full block (often up to 100ms).

This component defines which event to update and when. It takes the following parameters:

Event Name: The name of the event in BCI2000 to update.
Response Component Variable: The variable to which the event is to be set OR the variable which contains the new value of the event. Note- the variable is written as $VariableName.
Use Expression: If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the event.
Expression: The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the event is updated. Note- the user would have to use commands such as bci.Execute and SET EVENT to update the event in such cases. See Programming Reference:BCI2000Remote Class and User Reference:Operator Module Scripting for more details.

BCI2000UpdateState

This component defines which state to update and when. It takes the following parameters:

State Name: The name of the state in BCI2000 to update.
Response Component Variable: The variable to which the state is to be set OR the variable which contains the new value of the state. Note- the variable is written as $VariableName.
Use Expression: If it is checked, the code written in 'Expression' is executed for each Frame and the variable specified in the Response Component Variable is not used to update the state.
Expression: The code to execute for each Frame. It is given for the cases where the Response Component Variable is not available and the user wants more control over how the state is updated. Note- the user would have to use commands such as bci.Execute and SET STATE to update the state in such cases. See Programming Reference:BCI2000Remote Class and User Reference:Operator Module Scripting for more details.

Integrating BCI2000 into PyschoPy

Clone PsychoPy from the PyschoPy repository. You can also download the PsychoPy standalone version from the PsychoPy downloads page.
Below is a picture of PsychoPy before integrating BCI2000. Notice that in the rightmost column, under Custom Components, there is no BCI2000 component.

PsychoPy Homepage without BCI2000 Components

Standalone version

For Windows, Copy the folders BCIStart, BCIUpdateEvent, and BCIUpdateState from the src/contrib/PsychoPy Components directory of your BCI2000 repository into the folder {$PsychoPyHome}\Lib\site-packages\psychopy\experiment\components folder.

Developer version

Copy the folders BCIStart, BCIUpdateEvent, and BCIUpdateState from the src/contrib/PsychoPy Components directory of your BCI2000 repository into the folder {$PsychoPyHome}\psychopy\experiment\components. Open the terminal and navigate to the PsychoPy home directory where setup.py resides. Run the following command in the terminal:
pip install -e .

Start PsychoPy application by running "python \psychopy\app\psychopyApp.py" from wherever you cloned your PsychoPy repository. If you downloaded the standalone version installer, you can simply press the Windows key and search for PsychoPy. Once you're under the Custom Components (in the rightmost column), you should see the three new components - BCI2000Start, BCIUpdateEvent, and BCI2000UpdateState as shown in the figure below.

PsychoPy Homepage with BCI2000 Components

Note: Make sure you don't run the experiments in full screen if you are using a single screen.

Tutorial

In this section, two examples are presented to help the user understand the use of BCI2000 within PsychoPy. The examples modify the demo stroopExtended (already provided by PsychoPy once you have unpacked the demos) and integrates BCI2000 within it. The stroopExtended demo asks user to press certain keys depending on the color shown on the screen and records the response time.

Using Response Component Variable Option

In this tutorial, we will add a new event called correctKey in BCI2000 using PsychoPy. This event will be changed to 1 if the key pressed by user is correct, otherwise 0.

Open the stroopExtended demo in PsychoPy. It should look like this.
- PsychoPy Stroop Extended Demo

Start BCI2000 - Navigate to the instruct tab and click on BCI2000Start. Enter the path to the prog directory of BCI2000 (within which BCI2000Remote.py exists) in the Path field and correctKey 0 1
in the Events field as shown in the image. correctKey is the name we want the new event to have in BCI2000, 0 is the default value the event should have and 1 is the maximum value the event can take in any case.
- PsychoPy - Add Event into BCI2000

Update BCI2000 Event - Navigate to the trial tab and click on BCI2000UpdateEvent. Fill in the fields Event Name with $correctKey (the BCI2000 event we want to update; '$' is used to indicate to PsychoPy to treat it as a variable) and Response Component Variable with $resp.corr ('resp' is the name of the keyboard that takes the input and 'corr' is its property that stores whether the key pressed is correct or not. you can see this variable being used in the program when you compile it to script) as shown in the image. This will essentially update the event 'correctKey' with the value of 'resp.corr'.
- PsychoPy - Update Event in BCI2000

Run the experiment. BCI2000 will start. Add the newly created event to watch (in the BCI2000 operator, click on View -> States and Events.., right click on correctKey and add to watch, then click Ok on States and Events screen) and proceed as with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. Note: Make sure you don't run the experiments in full screen mode if you are using a single screen.
- PsychoPy Stroop Extended Demo Run 1

Using Use Expression Option

In this tutorial, we will add a new state called responseTime in BCI2000 using PsychoPy. This state will represent the time the user takes to press the correct key in seconds (with no decimals).

Open the stroopExtended demo in PsychoPy. It should look like the image below.
- PsychoPy Stroop Extended Demo

Start BCI2000 - Navigate to the instruct tab and click on BCI2000Start. Enter the path to the prog directory of BCI2000 (within which BCI2000Remote.py exists) in the Path field and responseTime 0 600
in the Events field as shown in the image. responseTime is the name we want the new event to have in BCI2000, 0 is the default value the event should have and 600 is the maximum value the event can take in any case, i.e, the maximum response time could be 10 minutes.
- PsychoPy - Add Event into BCI2000

Update BCI2000 Event - Navigate to the trial tab and click on BCI2000UpdateEvent. Check on the Use Expression option to run the expression that is written in the Expression field. Write the lines of python code in the Expression field as shown in the image. These lines first set the 'RUNNING' state of BCI2000 to 1 to make sure that BCI2000 is running. It then checks if the type of the 'resp.rt' is float. If yes, that means 'resp.rt' stores the response time and sets the event 'responseTime' to the rounded value of 'resp.rt' ('resp' is the name of the keyboard which takes the input and 'rt' is its property that stores the time it took user to press the key; you can see this variable being used in the program when you compile it to script) using the bci.Execute and SET EVENT commands.
bci.Execute('SET STATE RUNNING 1') if(type(resp.rt) == float): bci.Execute('SET EVENT responseTime %d' % round(resp.rt))
- PsychoPy - Update Event in BCI2000

Run the experiment. BCI2000 will start. Add the newly created event to watch (in the BCI2000 operator, click on View -> States and Events.., right click on responseTime and add to watch. Click Ok on the States and Events screen) and proceed with your PsychoPy experiment. The output of this experiment would be similar to the image shown below. Note: Make sure you don't run the experiments in full screen mode if you are using a single screen.
- PsychoPy Stroop Extended Demo Run 2