BCI & Brain Connectivity

This repository contains the code for the multiverse analysis of SNR and EEG-based phase synchronization as predictors of performance in a sensorimotor BCI training. Please refer to the accompanying paper for details and cite it if you use the code from this repository:

Kapralov, N., Jamshidi Idaji, M., Stephani, T., Studenova, A., Vidaurre, C., Ros, T., Villringer, A., & Nikulin, V. (2024). Sensorimotor brain-computer interface performance depends on signal-to-noise ratio but not connectivity of the mu rhythm in a multiverse analysis of longitudinal data. Journal of Neural Engineering, 21(5), doi: 10.1088/1741-2552/ad7a24

Prerequisites

1. MATLAB (tested with R2022b) and the following toolboxes/files (should be installed in the toolboxes folder, also possible using the make setup_toolboxes command in Linux):

• [link] Berlin Brain-Computer Interface (BBCI) toolbox. NOTE: toolboxes/BTB/BTB.mat is provided for the BBCI toolbox to run.
• [link] EEGLAB 2021.0. NOTE: The toolbox was manually set to use double precision in order to avoid problems when analyzing data outside of EEGLAB.
• [link] FastICA v2.5 (GPL, only required if performing preprocessing from scratch)
• [link] Pre-computed New York Head model
• [link] MATLAB Wrapper for FOOOF
• [link] tprod toolbox (GPL). NOTE: apparently, it is problematic to compile this toolbox in the newer versions of MATLAB - one could either do it in previous versions or try to use the compiled files from this repository.

2. Python with FOOOF installed (pip install fooof or use requirements.txt). NOTE: keep in mind the compatibility between different versions of MATLAB and Python.

3. R (tested with version 4.2.2) and a number of packages specified in the environment file (stats/renv.lock). renv::restore() can be used to install the required packages (some are licensed under GPL), more details are available here.

4. Local LaTeX environment for compiling the final PDF of the paper and supplementary material.

5. [Optional] For the Makefile to be useful, a Linux-based OS is required with the following utilities: wget, unzip, curl.

Folder Structure

• assets - images that are included in some of the figures. Some of them are generated through MATLAB scripts
• data - folder with all the data (added to .gitignore)
  • raw - original dataset
  • aux - preprocessing info
  • preproc
    • task1 - preprocessed data
  • derivatives
    • task1 - intermediate results (MATLAB)
    • r - intermediate results (R)
• paper - everything that is required for LaTeX
  • figures - here the generated figures are collected
  • numbers - here the generated output is collected
  • sections - sections of the manuscript
• results - figures & output for TeX that is generated by all scripts (added to .gitignore)
• scripts - MATLAB scripts
• stats - R scripts for statistical analysis
• toolboxes - folder with MATLAB toolboxes

Creating a Local Copy of the Project

1. Clone the master branch of the repository.

2. Set up all the prerequisites (see above).

3. Download the original dataset using make download_raw_data or manually by saving all files to the data/raw/ folder. If you downloaded the data earlier, you can create a symbolic link to the location of the data like shown below (scripts in this repository do not change the original files):

ln -s <location> ./data/raw

4. Download the preprocessing information using make download_aux_data or manually to the data/aux folder from the OSF repository.

5. Specify the path to a Python executable with FOOOF installed in line 7 of the file scripts/BCI_MI_analysis_main.m.

6. Specify the commands for running MATLAB and R in the lines 13 (MATLAB_ALIAS) and 15 (R_ALIAS) of the Makefile, respectively.

7. Launch the analysis using make all on Linux or follow the steps specified in the Makefile. Files scripts/BCI_MI_analysis_main.m and stats/main.R are the main entry points for the analyses performed in MATLAB and R, respectively.

8. [Optional] Run git status. If there are no changes detected, the results were repeated.