PyCNBI provides a real-time brain signal decoding framework. It has been applied on a couple of online decoding projects based on EEG and ECoG and on various acquisition systems including AntNeuro eego, g.tec gUSBamp, BioSemi ActiveTwo and BrainProducts actiCHamp. The decoding runs at approximately 15 Hz on a 3rd-gen i7 laptop with 64-channel setup at 512 Hz sampling rate. It has been tested on Windows 7 and 10 with Python 2.7 and 3.6. In principle, it should also run in Linux but I didn't have time to test yet.
The underlying data communication is based on Lab Streaming Layer (LSL) which provides sub-millisecond time synchronization accuracy. Any acquisition system supported by native LSL or OpenVibe is also supported by PyCNBI. Since the data communication is based on TCP, signals can be also transmitted wirelessly. For more information about LSL, please visit:
The base module for acquiring signals used by other modules such as Decoder, StreamViewer and StreamRecorder.
Visualize signals in real time with spectral filtering, common average filtering options and real-time FFT.
Record signals into fif format, a standard format also mainly used in MNE EEG analysis library.
Replay the recorded signals in real time as if it was transmitted from a real acquisition server.
This folder contains decoder and trainer modules. Currently, LDA, regularized LDA, Random Forests, and Gradient Boosting Machines are supported as the classifier type. Neural Network-based decoders are currently under experiment.
Contains some basic protocols for training and testing. Google Glass visual feedback is supported through USB communication.
Triggers are used to mark event (stimulus) timings during the recording. This folder contains common trigger event definition files.
Contains various utilities.
For easy installation of Python environment, Anaconda or Enthought Canopy is recommended.
PyCNBI depends on following packages:
- pylsl (see the note below for Python 3 users)
- scipy, numpy
- mne 0.14 or later
- scikit-learn (0.17 recommended. 0.19 has 12% slower RandomForest predict_proba() call)
- matplotlib 2.1.0 or later
- pyqt4 (For Windows users, you can download it from here)
You can install most of the packages using conda or pip. For the usage of pip, have a look here:
Optional but strongly recommended:
OpenVibe supports a wide range of acquisition servers and all acquisition systems supported by OpenVibe are supported by PyCNBI with LSL. Make sure you tick the checkbox "LSL_EnableLSLOutput" in Preferences when you run acquisition server. This will stream the data through the LSL network from which PyCNBI receives data.
Note: For pylsl, if you use Python 3, compile and install the latest LSL if the current version in pip (1.10.5) throws a run-time access violation error while handling XML headers caused by its pre-compiled C++ libraries. I have included a custom-compiled LSL library in pylsl folder, which you can manually copy to your Python distribution's library path.
Clone the repository:
git clone https://c4science.ch/source/pycnbi.git
Run setup script:
python setup.py develop
Add "scripts" directory to PATH environment variable for convenient access to commonly used scripts.
For g.USBamp acquisition system users
The following customized acquisition server is needed instead of default LSL app to receive the trigger channel as part of signal streaming channels:
git clone https://c4science.ch/diffusion/1300/gUSBamp_pycnbi.git
because the default gUSBamp LSL server do not stream event channel as part of the signal stream. The customized version supports simultaneous signal+event channel streaming. For AntNeuro eego systems, use the OpenVibe acquisition server and make sure to check "LSL output" in preference. If you don't see "eego" from the device selection, it's probably because you didn't install the additional drivers when you installed OpenVibe.
Hardware triggering without legacy parallel port
We have also developed an Arduino-based triggering system as we wanted to send triggers to a parallel port using standard USB ports. We achieved sub-millisecond extra latency compared to physical parallel port (150 +- 25 us). Experimental results using oscilloscope can be found in "doc" folder. The package can be downloaded by:
git clone https://c4science.ch/diffusion/1301/arduino-trigger.git
The customized firmware should be installed on Arduino Micro and the circuit design included in the document folder should be printed to a circuit board.
- GUI-based setting tools.
- Use .ini files instead of .py files for settings.
- More cpu-efficient decoder class.
There are still plenty of possibilities to optimize the speed in many parts of the code. Any contribution is welcome. Please contact email@example.com for any comment / feedback.
Copyright and license
The codes are released under GNU General Public License.