Skip to content

Commit

Permalink
Update READEs based on comments and lint the main README
Browse files Browse the repository at this point in the history
  • Loading branch information
@tab-cmd
tab-cmd committed Dec 30, 2024
1 parent a36ee91 commit 0ffb998
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 103 deletions.
178 changes: 80 additions & 98 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,22 @@
# BciPy: Brain-Computer Interface Software in Python


[![BciPy](https://github.com/CAMBI-tech/BciPy/actions/workflows/main.yml/badge.svg)](https://github.com/CAMBI-tech/BciPy/actions/workflows/main.yml)
[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](https://github.com/CAMBI-tech/BciPy/fork)
[![Follow on Twitter](https://img.shields.io/twitter/follow/cambi_tech?label=Follow&style=social)](https://twitter.com/cambi_tech)


BciPy is a library for conducting Brain-Computer Interface experiments in Python. It functions as a standalone application for experimental data collection or you can take the tools you need and start coding your own system. See our official BciPy documentation including affiliations and more context information [here](https://bcipy.github.io/).

It will run on the latest windows (7, 10, 11), linux (ubuntu 22.04) and macos (Big Sur). Other versions may work as well, but are not guaranteed. To see supported versions and operating systems as of this release see here: [BciPy Builds](https://github.com/CAMBI-tech/BciPy/actions/workflows/main.yml).

*Please cite us when using!*

```
```text
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.
```

## Dependencies
---------------
This project requires Python 3.8 or 3.9. Please see notes below for additional OS specific dependencies before installation can be completed and reference our documentation/FAQs for more information: https://bcipy.github.io/hardware-os-config/

This project requires Python 3.8 or 3.9. Please see notes below for additional OS specific dependencies before installation can be completed and reference our documentation/FAQs for more information: <https://bcipy.github.io/hardware-os-config/>

### Linux

Expand All @@ -33,27 +31,26 @@ You will need to install pyWinhook manually. See [here](https://www.lfd.uci.edu/

### 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 will 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 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 will 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 segementation fault when running BciPy. This is due to an issue in a dependeancy of psychopy with no known fix as of yet. Please use bash instead of zsh for now.
If using zsh, instead of bash, you may encounter a segementation fault when running BciPy. This is due to an issue in a dependeancy 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 following the dependencies above, you will need to install the BciPy package.

To install for use locally and use of the GUI:
1. Git clone https://github.com/BciPy/BciPy.git

1. Git clone <https://github.com/BciPy/BciPy.git>.
2. Change directory in your terminal to the repo directory.
3. Install the kenlm language model package. `pip install kenlm==0.1 --global-option="--max_order=12"`.
4. Install PsychoPy with no dependencies. `pip install psychopy==2023.2.1 --no-deps`.
5. Install BciPy in development mode. `pip install -e .`

5. Install BciPy in development mode. `pip install -e .`.

If wanting the latest version from PyPi and to build using modules:

1. `pip install bcipy`

Alternately, if [Make](http://www.mingw.org/) is installed, you may run the follow command to install:
Expand All @@ -64,87 +61,91 @@ make dev-install
```

### Client Usage
----------------

##### Run an experiment protocol or task
#### Run an experiment protocol or task

Invoke an experiment protocol or task directly using command line utility `bcipy`.

- Use the help flag to see other available input options: `bcipy --help`
- You can pass it attributes with flags, if desired.
- Running with a User ID and Task:
- `bcipy --user "bci_user" --task "RSVP Calibration"`
- Running with a User ID and Tasks with a registered Protocol:
- `bcipy --user "bci_user" --experiment "default"`
- Running with fake data:
- `bcipy --fake`
- Running without visualizations:
- `bcipy --noviz`
- Running with alerts after each Task execution:
- `bcipy --alert`
- Running with custom parameters:
- `bcipy --parameters "path/to/valid/parameters.json"`
Use the help flag to see other available input options: `bcipy --help`

You can pass it attributes with flags, if desired.

- Run with a User ID and Task:
- `bcipy --user "bci_user" --task "RSVP Calibration"`
- Run with a User ID and Tasks with a registered Protocol:
- `bcipy --user "bci_user" --experiment "default"`
- Run with fake data:
- `bcipy --fake`
- Run without visualizations:
- `bcipy --noviz`
- Run with alerts after each Task execution:
- `bcipy --alert`
- Run with custom parameters:
- `bcipy --parameters "path/to/valid/parameters.json"`

##### Train a signal model with registered BciPy models
#### Train a signal model with registered BciPy models

To train a signal model (currently `PCARDAKDE` and `GazeModels`), run the following command after installing BciPy:

`bcipy-train`

- Use the help flag to see other available input options: `bcipy-train --help`
- You can pass it attributes with flags, if desired.
- Running without a window prompting for data session folder:
- `bcipy-train -d path/to/data`
- Running with data visualizations (ERPs, etc.):
- `bcipy-train -v`
- Running with data visualizations that do not show, but save to file:
- `bcipy-train -s`
- Running with balanced accuracy:
- `bcipy-train --balanced-acc`
- Running with alerts after each Task execution:
- `bcipy-train --alert`
- Running with custom parameters:
- `bcipy-train -p "path/to/valid/parameters.json"`
Use the help flag to see other available input options: `bcipy-train --help`

You can pass it attributes with flags, if desired.

- Run without a window prompting for data session folder:
- `bcipy-train -d path/to/data`
- Run with data visualizations (ERPs, etc.):
- `bcipy-train -v`
- Run with data visualizations that do not show, but save to file:
- `bcipy-train -s`
- Run with balanced accuracy:
- `bcipy-train --balanced-acc`
- Run with alerts after each Task execution:
- `bcipy-train --alert`
- Run with custom parameters:
- `bcipy-train -p "path/to/valid/parameters.json"`

##### Visualize ERP data from a session with Target / Non-Target labels
#### Visualize ERP data from a session with Target / Non-Target labels

To generate plots that can be shown or saved after collection of data, run the following command after installing BciPy:

`bcipy-erp-viz`

- Use the help flag to see other available input options: `bcipy-erp-viz --help`
- You can pass it attributes with flags, if desired.
- Running without a window prompting for data session folder:
- `bcipy-erp-viz -s path/to/data`
- Running with data visualizations (ERPs, etc.):
- `bcipy-erp-viz --show`
- Running with data visualizations that do not show, but save to file:
- `bcipy-erp-viz --save`
- Running with custom parameters (default is in bcipy/parameters/parameters.json):
- `bcipy-erp-viz -p "path/to/valid/parameters.json"`
Use the help flag to see other available input options: `bcipy-erp-viz --help`

##### BciPy Simulator Usage
You can pass it attributes with flags, if desired.

- Run without a window prompt for a data session folder:
- `bcipy-erp-viz -s path/to/data`
- Run with data visualizations (ERPs, etc.):
- `bcipy-erp-viz --show`
- Run with data visualizations that do not show, but save to file:
- `bcipy-erp-viz --save`
- Run with custom parameters (default is in bcipy/parameters/parameters.json):
- `bcipy-erp-viz -p "path/to/valid/parameters.json"`

#### BciPy Simulator Usage

The simulator can be run using the command line utility `bcipy-sim`.

Ex.
`bcipy-sim -d my_data_folder/ -p my_parameters.json -m my_models/ -n 5`
To run the simulator with a single data folder, a custom parameters file, a trained model, and 5 iterations, use the following command:

Run `bcipy-sim --help` for documentation or see the README in the simulator module.
`bcipy-sim -d my_data_folder/ -p my_parameters.json -m my_models/ -n 5`

For more information or to see other available input options, use the help flag: `bcipy-sim --help`. In addition, more information can be found in the simulator module README.

### Package Usage
-------------------
### Package Usage

```python
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:

```sh
python bcipy/gui/BCInterface.py
```
Expand All @@ -155,9 +156,7 @@ Alternately, if Make is installed, you may run the follow command to start the G
make bci-gui
```


## Glossary
-----------

***Stimuli***: A single letter, tone or image shown (generally in an inquiry). Singular = stimulus, plural = stimuli.

Expand All @@ -177,9 +176,7 @@ make bci-gui

***Paradigm***: Display paradigm with unique properties and modes. Ex. Rapid-Serial Visual Presentation (RSVP), Matrix Speller, Steady-State Visual Evoked Potential (SSVEP).


## Core Modules
---------------

This a list of the major modules and their functionality. Each module will contain its own README, demo and tests. Please check them out for more information!

Expand All @@ -197,40 +194,33 @@ This a list of the major modules and their functionality. Each module will conta
- `config`: configuration parameters for the application, including paths and data filenames.
- `simulator`: provides support for running simulations based off of previously collected data.


## Paradigms
------------

See `bcipy/task/README.md` for more information on all supported paradigms, tasks, actions and modes. The following are the supported and validated paradigms:

### RSVPKeyboard

> RSVPKeyboard

```
*RSVP KeyboardTM* is an EEG (electroencephalography) based BCI (brain computer interface) typing system. It utilizes a visual presentation technique called rapid serial visual presentation (RSVP). In RSVP, the options are presented rapidly at a single location with a temporal separation. Similarly in RSVP KeyboardTM, the symbols (the letters and additional symbols) are shown at the center of screen. When the subject wants to select a symbol, they await the intended symbol during the presentation and elicit a p300 response to a target symbol.
```

Citation:
```
References:

```text
Orhan, U., Hild, K. E., 2nd, Erdogmus, D., Roark, B., Oken, B., & Fried-Oken, M. (2012). RSVP Keyboard: An EEG Based Typing Interface. Proceedings of the ... IEEE International Conference on Acoustics, Speech, and Signal Processing. ICASSP (Conference), 10.1109/ICASSP.2012.6287966. https://doi.org/10.1109/ICASSP.2012.6287966
```

> Matrix Speller
### Matrix Speller

```
Matrix Speller is an EEG (electroencephalography) based BCI (brain computer interface) typing system. It utilizes a visual presentation technique called Single Character Presentation (SCP). In matrix speller, the symbols are arranged in a matrix with fixed number of rows and columns. Using SCP, subsets of these symbols are intensified (i.e. highlighted) usually in pseudorandom order to produce an odd ball paradigm to induce p300 responses.
```
Matrix Speller is an EEG (electroencephalography) based BCI (brain computer interface) typing system. It utilizes a visual presentation technique called Single Character Presentation (SCP). In matrix speller, the symbols are arranged in a matrix with fixed number of rows and columns. Using SCP, subsets of these symbols are intensified (i.e. highlighted) usually in pseudorandom order to produce an odd ball paradigm to induce p300 responses.

Citation:
```
References:

```text
Farwell, L. A., & Donchin, E. (1988). Talking off the top of your head: toward a mental prosthesis utilizing event-related brain potentials. Electroencephalography and clinical Neurophysiology, 70(6), 510-523.
Ahani A, Moghadamfalahi M, Erdogmus D. Language-Model Assisted And Icon-based Communication Through a Brain Computer Interface With Different Presentation Paradigms. IEEE Trans Neural Syst Rehabil Eng. 2018 Jul 25. doi: 10.1109/TNSRE.2018.2859432.
```

## Demo
--------

All major functions and modules have demo and test files associated with them which may be run locally. This should help orient you to the functionality as well as serve as documentation. *If you add to the repo, you should be adding tests and fixing any test that fail when you change the code.*

Expand All @@ -240,16 +230,14 @@ For example, you may run the main BciPy demo by:

This demo will load in parameters and execute a demo task defined in the file. There are demo files contained in most modules, excepting gui, signal and parameters. Run them as a python script!


## Offset Determination and Correction
--------------------------------------

Static offset determination and correction are critical steps before starting an experiment. BciPy uses LSL to acquire EEG data and Psychopy to present stimuli.
Static offset determination and correction are critical steps before starting an experiment. BciPy uses LSL to acquire EEG data and Psychopy to present stimuli. The synchronization between the two systems is crucial for accurate data collection and analysis.

[LSL synchronization documentation](https://labstreaminglayer.readthedocs.io/info/time_synchronization.html)
[PsychoPy timing documentation](https://www.psychopy.org/general/timing/index.html)

A static offset is the regular time difference between our signals and stimuli. This offset is determined through testing via a photodiode or other triggering mechanism. The offset correction is done by shifting the EEG signal by the determined offset using the `static_offset` parameter.
A static offset is the regular time difference between our signals and stimuli. This offset is determined through testing via a photodiode or other triggering mechanism. The offset correction is done by shifting the EEG signal by the determined offset using the `static_offset` parameter.

After running a timing verification task (such as, RSVPTimingVerification) with a photodiode attached to the display and connected to a device, the offset can be determined by analyzing the data. Use the `offset` module to recommend an offset correction value and display the results.

Expand All @@ -273,7 +261,6 @@ make offset-recommend
```

## Testing
----------

When writing tests, put them in the correct module, in a tests folder, and prefix the file and test itself with `test_` in order for pytest to discover it. See other module tests for examples!

Expand All @@ -285,7 +272,6 @@ To run all tests, in the command line:
py.test
```


To run a single modules tests (ex. acquisition), in the command line:

```python
Expand All @@ -311,7 +297,6 @@ make coverage-html
```

## Linting
----------

This project enforces `PEP` style guidelines using [flake8](http://flake8.pycqa.org/en/latest/).

Expand All @@ -334,7 +319,6 @@ make lint
```

## Type Checking
----------------

This project enforces `mypy` type checking. The typing project configuration is found in the mypy.ini file. To run type checking, run the following command:

Expand All @@ -354,30 +338,28 @@ Alternately, if Make is installed, you may run the follow command to run mypy:
make type
```

### Contributions Welcome

### Contributions Welcome!
--------------------------

If you want to be added to the development team slack or have additional questions, please reach out to us at [email protected]!
If you want to be added to the development team slack or have additional questions, please reach out to us at <[email protected]>!

#### Contribution Guidelines

We follow and will enforce the contributor's covenant to foster a safe and inclusive environment for this open source software, please reference this link for more information: https://www.contributor-covenant.org/
We follow and will enforce the contributor's covenant to foster a safe and inclusive environment for this open source software, please reference this link for more information: <https://www.contributor-covenant.org/>

We welcome all contributions to BciPy! Please follow the guidelines below:

Other guidelines:
- All modules require tests and a demo.
- All tests must pass to merge, even if they are seemingly unrelated to your work.
- Use Spaces, not Tabs.
- Use informative names for functions and classes.
- Document the input and output of your functions / classes in the code. eg in-line commenting and typing.
- Do not push IDE or other local configuration files.
- All new modules or major functionality should be documented outside of the code with a README.md.
See README.md in repo or go to this site for inspiration: https://github.com/matiassingers/awesome-readme. Always use a Markdown interpreter before pushing.
-- See README.md in repo or go to this site for inspiration: <https://github.com/matiassingers/awesome-readme>. Always use a Markdown interpreter before pushing.

See this resource for examples: http://docs.python-guide.org/en/latest/writing/style/
See this resource for examples: <http://docs.python-guide.org/en/latest/writing/style/>

### Contributors
---------------

All contributions are greatly appreciated!

Expand Down
6 changes: 1 addition & 5 deletions bcipy/signal/evaluate/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,11 +104,7 @@ epochs = mne_epochs(mne_data, trial_length, preload=True, reject_by_annotation=T

The `calculate_eeg_gaze_fusion_acc` function is used to evaluate the performance of the BCI system. The function takes in a list of EEG and gaze data, and returns the accuracy of the fusion of the two signals. The function uses the following steps to calculate the accuracy:

1. The data is loaded into the system and preprocessed.
2. The data is passed through the EEG and gaze models to generate predictions.
3. The predictions are fused together to generate a final prediction.
4. The final prediction is compared to the actual data to calculate the accuracy.
5. The accuracy is returned to the user.
The data is split into train and test sets for generating accuracy metrics. Predictions are generated for both single modal and multimodal cases, where multimodal predictions are generated by using Bayesian Fusion. The accuracy of the predictions is then calculated and returned.

### Fusion Usage

Expand Down

0 comments on commit 0ffb998

Please sign in to comment.