An example video showing one channel of the CCEP filter.

A demo of the Phase-Amplitude Coupling visualization with Python

Synopsis

Visualize your BCI2000 signals real-time with python! This integration allows for you to combine complex Signal Processing pipelines in C++ with beautiful, interactive visualizations in Python.

There are currently two prepared visualizations: Cortico-cortical evoked potentials (CCEPs) and phase-amplitude coupling (PAC). However, the pipeline is adaptable, allowing you to visualize whatever you want!

Installation

Python 3.7+ needs to be installed. You can download the lastest version here.
A couple additional packages are used in this visualization. Run the following segments using pip in the command line.
- Numpy: pip install numpy
- PyQt5: pip install PyQt5
- PyQtGraph 0.13.3+: pip install pyqtgraph
- SciPy: pip install scipy (only the stats package is required)

Configuration

Below is an example runnable script that will start BCI2000, along with the PAC visualization. This replaces the need for batch files, and allows you to easily run BCI2000 programmatically. Additional commands are available at Programming Reference:BCI2000Remote Class.

The only parameter is the path to your BCI2000Remote executable, which is in the prog folder of your BCI2000 directory. Make sure this is correct.

from scripts.main import main

#configure to customize your BCI2000 instance
def initBCI2000(bci):
    bci.WindowVisible = True
    bci.WindowTitle = 'BCI2000: Phase-Amplitude coupling'
    bci.Connect()
    bci.Execute('cd ${BCI2000LAUNCHDIR}')
    #FilePlayback is helpful if you already have the data file
    bci.StartupModules(('FilePlayback --PlaybackFileName=..\data\BJH041\ECOGS001R02.dat', 
                        'PAC', 
                        'DummyApplication'))
    bci.Execute('Wait for Connected')
    bci.LoadParametersRemote('../parms/PAC/pac_pipeline.prm')
    bci.Execute('SET PARAMETER AngleDecimation 6')
    bci.Execute('SET PARAMETER TransmitChList 65-80') #can choose whatever channels you want

if __name__ == '__main__':
    #choose your own bci2000 instance
    path = 'C:\\BCI2000\\prog'
    main(path, initBCI2000)

Architecture

Once BCI2000 is configured and built, these files are used to visualize your signal in BCI2000 in real-time with Python:

BCI2000
- python
  - visualizations - contains "batch" files that you can run to start BCI2000 and the python visualization
    - connect_batch.py - run this to connect to a batch file you have started
    - pacDemo.py
    - ccepDemo.py
    - scripts
      - main.py - starts the 2 secondary threads: data collection thread and BCI2000 connection thread
      - AcquireDataThread.py - thread that handles the data collection from the shared memory
      - BCI2000Connection.py - thread that handles the communication with the BCI2000 instance
      - CCEPVisualization.py - specifies how to handle the incoming data into the CCEP visualization
      - PACVisualization.py: - specifies how to do the same for the PAC visualization

These files can be moved around, however make sure to always keep the architecture under visualizations the same.

Python

3 threads are running within the Python scripts.

Data acquisition: Connects to the shared memory address and continually updates the local data when there is new data to be acquired.
BCI2000 Connection: Using BCI2000Remote, we have a two-way connection between Python and BCI2000. This is used for updating and acquiring states and parameters. This can also be used to start a BCI2000 instance, instead of the common practice of using a batch file.
Visualization: The main thread of the Python script creates an interactive visualization with PyQtGraph. When the visualization is interacted with, BCI2000 states are updated accordingly.