BciPy: Brain-Computer Interface Software in Python

BciPy is a library for conducting Brain-Computer Interface experiments in Python. It is designed to be modular and extensible, allowing researchers to easily add new paradigms, models, and processing methods. The focus of BciPy is on paradigms for communication and control, including Rapid Serial Visual Presentation (RSVP) and Matrix Speller. See our official documentation including affiliations and more context information here.

BciPy is released open-source under the BSD-3 clause. Please refer to LICENSE.md.

If you use BciPy in your research, please cite the following manuscript:

Memmott, T., Koçanaoğulları, A., Lawhead, M., Klee, D., Dudy, S., Fried-Oken, M., & Oken, B. (2021). BciPy: brain–computer interface software in Python. Brain-Computer Interfaces, 1-18.

Table of Contents

• BciPy: Brain-Computer Interface Software in Python
  • Table of Contents
  • Dependencies
    • Linux
    • Windows
    • Mac
  • Installation
    • BciPy Setup
      • Editable Install and GUI usage
      • PyPi Install
      • Make install
  • Usage
    • Package Usage
    • GUI Usage
    • Client Usage
      • General Usage
      • Running Experiments or Tasks via Command Line
        • Options
      • Train a Signal Model via Command Line
        • Basic Commands Signal Model Training
      • Visualize ERP data from a session with Target / Non-Target labels via Command Line
        • Basic Commands ERP Viz
    • BciPy Simulator
      • Running the Simulator
        • Basic Commands Simulator
        • Other Options
  • Core Modules
    • Top-Level Modules Overview
      • Acquisition
      • Core
      • Display
      • Feedback
      • GUI
      • Helpers
      • IO
      • Language
      • Signal
      • Simulator
      • Task
    • Entry Point and Configuration Modules
      • main.py
      • parameters/
      • config.py
      • static/
  • Paradigms
    • RSVPKeyboard
    • Matrix Speller
  • Offset Determination and Correction
    • What is a Static Offset?
      • How to Determine the Offset
      • Running Offset Determination
      • Applying the Offset Correction
      • Using Make for Offset Determination
      • Additional Resources
  • Glossary
  • Scientific Publications using BciPy
    • 2025
    • 2024
    • 2023
    • 2022
    • 2021
    • 2020
  • Contributions Welcome
    • Contribution Guidelines
    • Contributors

Dependencies

This project requires Python 3.9, 3.10 or 3.11.

It will run on the latest windows (10, 11), linux (ubuntu 22.04) and macos (Sonoma). Other versions may work as well, but are not guaranteed. To see supported versions and operating systems as of this release see our GitHub builds: BciPy Builds. Please see notes below for additional OS specific dependencies before installation can be completed and reference our documentation here: https://bcipy.github.io/hardware-os-config/

Linux

You will need to install the prerequisites defined in scripts\shell\linux_requirements.sh as well as pip install attrdict3.

Windows

If you are using a Windows machine, you will need to install the Microsoft Visual C++ Build Tools.

Mac

If you are using a Mac, you will need to install XCode and enable command line tools. xcode-select --install. If using an m1/2 chip, you may need to use the install script in scripts/shell/m2chip_install.sh to install the prerequisites. You may also need to use the Rosetta terminal to run the install script, but this has not been necessary in our testing using m2 chips.

If using zsh, instead of bash, you may encounter a segmentation fault when running BciPy. This is due to an issue in a dependency of psychopy with no known fix as of yet. Please use bash instead of zsh for now.

Installation

BciPy Setup

In order to run BciPy on your computer, after ensuring the OS dependencies above are met, you can proceed to install the BciPy package.

Editable Install and GUI usage

If wanting to run the GUI or make changes to the code, you will need to install BciPy in editable mode. This will ensure that all dependencies are installed and the package is linked to your local directory. This will allow you to make changes to the code and see them reflected in your local installation without needing to reinstall the package.

1. Git clone https://github.com/BciPy/BciPy.git.
2. Change directory in your terminal to the repo directory.
3. Install BciPy in development mode.

  pip install -e .

PyPi Install

If you do not want to run the GUI or make changes to the code, you can install BciPy from PyPi. This will install the package and all dependencies, but will not link it to your local directory. This means that any changes you make to the code will not be reflected in your local installation. This is the recommended installation method if wanting to use the modules without making changes to the BciPy code.

pip install bcipy

Make install

Alternately, if Make is installed, you may run the follow command to install:

# install in development mode with all testing and demo dependencies
make dev-install

Usage

The BciPy package may be used in two ways: via the command line interface (CLI) or via the graphical user interface (GUI). The CLI is useful for running experiments, training models, and visualizing data without needing to run the GUI. The GUI is useful for running experiments, editing parameters and training models with a more user-friendly interface.

Package Usage

To run the package, you will need to import the modules you want to use. For example, to run the the system info module, you can run the following:

from bcipy.helpers import system_utils
system_utils.get_system_info()

GUI Usage

Run the following command in your terminal to start the BciPy GUI:

python bcipy/gui/BCInterface.py

Alternately, if Make is installed, you may run the follow command to start the GUI from the BciPy root directory:

make bci-gui

Client Usage

Once BciPy is installed, it can be used via the command line interface. This is useful for running experiments, training models, and visualizing data without needing to run the GUI.

General Usage

Use the help flag to explore all available options:

bcipy --help

Running Experiments or Tasks via Command Line

You can invoke an experiment protocol or task directly using the bcipy command-line utility. This allows for flexible execution of tasks with various configurations.

Options

# Run with a User ID and Task
bcipy --user "bci_user" --task "RSVP Calibration"

# Run with a User ID and Experiment Protocol
bcipy --user "bci_user" --experiment "default"

# Run with Simulated Data
bcipy --fake

# Run without Visualizations
bcipy --noviz

# Run with Alerts after Task Execution
bcipy --alert

# Run with Custom Parameters
bcipy --parameters "path/to/valid/parameters.json"

These options provide flexibility for running experiments tailored to your specific needs.

Train a Signal Model via Command Line

To train a signal model (e.g., PCARDAKDE or GazeModels), use the bcipy-train command.

Basic Commands Signal Model Training

# Display help information
bcipy-train --help

# Train using data from a specific folder
bcipy-train -d path/to/data

# Display data visualizations (e.g., ERPs)
bcipy-train -v

# Save visualizations to a file without displaying them
bcipy-train -s

# Train with balanced accuracy metrics
bcipy-train --balanced-acc

# Receive alerts after each task execution
bcipy-train --alert

# Us