Home
The BeMoBIL Pipeline is an open-source MATLAB toolbox for fully synchronized, automatic, transparent, and replicable import, processing and visualization of mobile brain/body imaging and other EEG data. It includes wrappers for EEGLAB functions, the use of various EEGLAB plugins, and comes with additional new functionalities.
All parameters are configurable in central scripts and everything is stored in the EEG.etc struct. Additionally, analytics plots are generated for each step.
If you have any comments, questions, or suggestions, please open issues here on git, join our discord server, or write an email to [email protected]!
A guide to setting up the necessary tools and dependencies for the pipeline can be found here.
-
Seamless integration of the lab streaming layer
.xdfdata format as well as BIDS import. -
A robust preprocessing protocol including automatic noise removal, robust bad channel detection and interpolation, and full rank average referencing.
-
Independent Component Analysis with suitable prerequisites and including automatic time-domain artifact removal, as well as fitting of EEG equivalent dipoles and automatic classification of components and final cleaning of the data.
-
An easy-to-use central configuration file that contains all relevant tunable parameters (and explanations). It is optimized for MoBI data, which is typically contaminated with motion artifacts (more muscle movement, cable sway, fluctuating line noise...), but should be also applicable on stationary data with minor parameter tuning. Using the configuration struct, users can also easily customize the pipeline to fit the needs of their own data.
-
Each processing step is documented within the EEG.etc struct and analytics plots are generated throughout the process to enable quick and effective checks of the data.
-
Additionally, the pipeline includes preprocessing of motion data that is synchronized to the EEG data at import. This way, users are able to analyze the EEG and motion streams "together", meaning that events extracted from motion data can be copied to the EEG data, for example.
-
A functionality to improve the group level analysis for sources (ICs) by using a repeated clustering approach that optimizes the clustering for a given region of interest.
For a quick start, we recommend you to have a look at the following scripts in the root directory of the pipeline.
example_bemobil_config.m
example_bemobil_import.m
example_bemobil_process_all_EEG_data.m
example_bemobil_process_all_motion_data.m
The scripts example_bemobil_import.m, example_bemobil_process_all_EEG_data.m and example_bemobil_process_all_motion_data.m will all load example_bemobil_config.m. So the configuration file serves as the summary of settings used throughout the pipeline. Comments within the files explain the parameters. These scripts are the only scripts that need to be run. They contain all steps from the source xdf data over the raw imported data to the processed and cleaned data, and allow batch processing of all subjects.
The example_bemobil_import.m script contains an exemplary import process from xdf over BIDS to EEGLAB structure. If you already have your data in EEGLAB set files you may skip this step entirely, if you have your data already in BIDS, you can just run the bottom part that loads from BIDS to EEGLAB set. Specific instruction is given as comments.
Here is an example of the final BeMoBIL pipeline output :
In the single subject EEG analysis folder there are two final data sets after the complete processing is done (xxx_preprocessed_and_ICA.set and xxx_cleaned_with_ICA.set). Both sets have basic preprocessing done (line noise removal, channel locations, channel interpolation, removal of very slow trends), and contain ICA information. The xxx_cleaned_with_ICA.set file additionally has ICs removed as determined by the settings for ICLabel in the pipeline config. If ICA was only meant to be used for cleaning, any kind of sensor-level analysis (like ERPs at Pz electrode) can now be performed on the cleaned data. If the end goal is source analysis, and potentially analysis of muscle or eye activity in conjunction with other MoBI modalities, this data is still available in xxx_preprocessed_and_ICA.set. Consider our repeated clustering approach in that case.
Importing data is either done by just loading an EEGLAB .set file if the data is already present in this format, or by using the BeMoBIL BIDS Tools if the source data is in .xdf format.
The BeMoBIL BIDS tools consist of two levels:
- bemobil_xdf2bids to convert raw .xdf files (as created by lab streaming layer) into BIDS format
- bemobil_bids2set to convert BIDS-formatted data to synchronized EEGLAB file formats
Depending on the data it can also be loaded in BIDS using FieldTrip or EEGLAB.
If the data is provided in EEGLAB .set format this should be stored in 2_raw-EEGLAB and these data sets can be used right away.
After the data is imported into EEGLAB, it can be processed fully automatically. The steps, reasoning, and parameters are described here.
The processing consists of two main parts:
- Preprocessing, containing line noise removal, bad channel detection and interpolation, and average referencing
- AMICA processing, containing high-pass filtering, AMICA, dipole fitting, and labeling of ICs
This can be looped over all subjects (see example_bemobil_process_all_EEG_data.m for an example). During or after the processing, it is important to check the analytics plots as described in this guide.
The BeMoBIL pipeline also contains automatic cleaning and processing of motion data, including computing derivatives and generating basic motion onset and offset events. This guide describes the steps in details. This can be looped over all subjects (see example_bemobil_process_all_motion_data.m for an example).
Eye data can be analyzed in addition, where blink events are detected and interpolated automatically. The processing is described here. This can be looped over all subjects (see example_bemobil_process_all_eye_data.m for an example).
Lastly, heart beats can be detected using the Pan-Tompkins algorithm as described here. While high-density EEG may contain a usable heart-component, it is risky to process and trust this automatically, which is why no complete automatic example script exists for this.
No algorithm is perfect. While we strive to create a pipeline that runs fully automatic once it is set up, we cannot guarantee the quality of the results. Hence, the pipeline includes figures for many steps that allow checking the entire process and see whether things look as they should. These are located within the folders of each participant in each level, and a script is provided that copies them all in a top level folder (see processing example). In this guide we explain the figures and their interpretation in detail.
Clustering independent components for group-level source analysis is not a trivial task and using the standard k-means approach provided by EEGLAB, it is not guaranteed that the results are reproducible. This guide explains the problem and our solution based on a repeated clustering approach.
The toolbox contains several additional miscellaneous functions ranging from an automatic detection of bad epochs over additional signal decomposition options to specific plot options for motion and eye data. Here, we describe the most important functions and their use.