brain-python-interface (a.k.a. bmi3d)

This the python 3 branch. It has not been as extensively tested as the python 2 version on the master branch. However, the python 2 version is no longer being actively maintained.

This package contains Python code to run electrophysiology behavioral tasks, with emphasis on brain-machine interface (BMIs) tasks. This package differs from other similar packages (e.g., BCI2000--http://www.schalklab.org/research/bci2000) in that it is primarily intended for intracortical BMI experiments.

This package has been used with the following recording systems:

• Omniplex neural recording system (Plexon, Inc.).
• Blackrock NeuroPort

Code documentation can be found at http://carmenalab.github.io/bmi3d_docs/

Getting started

Dependencies

Ubuntu

sudo xargs apt-get -y install < requirements.system

Windows

Visual C++ Build tools (for the 'traits' package)

Installation

This package depends on many other python packages and is sensitive to the version numbers of some of those dependencies. For that reason, it is recommended that you install into a virtual environment to isolate the python packages for bmi3d from the rest of your system python use:

git clone -b develop https://github.com/carmenalab/brain-python-interface.git
cd brain-python-interface
python3 -m venv env                 # create virtual environment for python package isolation
source env/bin/activate             # open virtual environment
pip install -r requirements.txt
pip install -e .                    # install in editable mode. Now 'git pull' updates in this directory will automatically propagate to the installation
deactivate                          # exit virtual environment

OS X

After installing the main requirements, you also need to install pygame

source env/bin/activate             # open virtual environment
pip instal -r requirements_osx.txt
deactivate                          # exit virtual environment

Installation in Docker

• Set up docker on Ubuntu following these instructions: https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-20-04
• In the install folder, execute build_docker.sh to build the image
• Also in the install folder, execute run_docker.sh to load the image. Annoyingly at this time, because the source directory is mounted in a way that is volatile, the bash shell will 'reinstall' the bmi3d package every time you load the image

Graphics generation from inside the image has only been tested in Ubuntu. To test, load the image using run_docker.sh and

cd /src/tests/unit_tests/
python3 test_built_in_vfb_task.py

If successful, you'll see the pygame window pop up looking like a poorly-made video game. If unsuccessful, you'll see the graphics in the terminal itself in ASCII art.

Setting up the database

cd db
touch db.sql                   # Make empty file for database
python3 manage.py makemigrations
python3 manage.py migrate
python3 manage.py makemigrations tracker
python3 manage.py migrate                  # make sure to do this twice!

Start server

python3 manage.py runserver

Setup paths and configurations

Once the server is running, open up Chrome and navigate to localhost:8000/setup

• Under "Subjects", make sure at least one subject is listed. A subject named "test" is recommended for separating exploration/debugging from real data.

• Under "tasks", add a task to the system by giving it the python path for your task class. See documentation link above for details on how to write a task. There are a couple of built in tasks to help you get started.

  • For example, you can add the built-in task riglib.experiment.mocks.MockSequenceWithGenerator just to check that the user interface works
  • If you want to try something graphical, you can add the built-in task built_in_tasks.passivetasks.TargetCaptureVFB2DWindow. This will be a "visual feedback" task in which a cursor automatically does the center-out task, a standard task in motor ephys.

Run a task

Navigate to http://localhost:8000/exp_log/ in chrome. Then press 'Start new experiment' and run your task.

Remote access

On Ubuntu, use the ufw package to open the port that Django is using

sudo ufw allow 8000/tcp
sudo ufw allow ssh
sudo ufw enable    # this is needed even if raspi-config enables SSH

Then start the server with

python3 manage.py runserver 0.0.0.0:8000

Remote access

On Ubuntu, use the ufw package to open the port that Django is using

sudo ufw allow 8000/tcp
sudo ufw allow ssh
sudo ufw enable    # this is needed even if raspi-config enables SSH

Then start the server with

python3 manage.py runserver 0.0.0.0:8000

Troubleshooting

This package has a lot of dependencies which makes installation somewhat brittle due to versions of different dependencies not getting along.

• Installation in a virtual environment (see venv in python3) or in a Docker container is recommended to try to isolate the package from version conflict issues.
• Run scripts in tests/unit_tests/ to try to isolate which components may not be working correctly. Issues in riglib will be easier to fix than issues in the database.

Running javascript tests

Javascript tests require the qunit library. To run the tests from the browser, open up db/html/static/resources/js/qunit.html in your browser of choice for running experiments.

If you are developing in javascript, you may want to run the tests from the command line. To install the qunit command-line setup, execute as root

cd db/html/static/resources/js
apt install npm
npm install -g qunit
npm install jquery
npm install jsdom

Then run qunit to run the tests in the test folder.

Papers which have used this package

• Ramos Murguialday et al., A Novel Implantable Hybrid Brain-Machine-Interface (BMI) for Motor Rehabilitation in Stroke Patients. IEEE NER 2019
• Khanna P. and Carmena J.M. (2017) Beta band oscillations in motor cortex reflect neural population signals that delay movement onset. eLife 6:e24573. doi:10.7554/eLife.24573.
• Moorman H.G., Gowda S. and Carmena J.M. (2017) Control of redundant kinematic degrees of freedom in a closed-loop brain-machine interface. IEEE Transactions on Neural Systems and Rehabilitation Engineering 25(6), pp. 750-760. doi:10.1109/TNSRE.2016.2593696.
• Shanechi M.M., Orsborn A.L., Moorman H.G., Gowda S., Dangi S., and Carmena J.M. (2017) Rapid control and feedback rates in the sensorimotor pathway enhance neuroprosthetic control. Nature Communications 8:13825. doi:10.1038/ncomms13825.
• Dangi S., Gowda S., Moorman H.G., Orsborn A.L., So K., Shanechi M. and Carmena J.M. (2014) Continuous closed-loop decoder adaptation with a recursive maximum likelihood algorithm allows for rapid performance acquisition in brain-machine interfaces. Neural Computation 12, pp. 1-29.