PyBeMoBIL#

PyBeMoBIL is a Python library for EEG and multimodal Mobile Brain/Body Imaging (MoBI) data processing, developed at the Biopsychology & Neuroergonomics department at TU Berlin.

It provides a full analysis stack built on top of MNE-Python:

  • Multimodal loading - read XDF recordings and align auxiliary streams (ECG, gaze, EMG, EDA) to a common time grid using the XDFLoader.

  • EEG preprocessing pipeline - ZapLine line-noise removal → bad channel detection → bandpass filter → optional ASR → JAMICA/ICA → ICLabel classification → dipole fitting, all in one EEGPreprocessor call with full provenance tracking.

  • BIDS export - write cleaned datasets to the BIDS standard via export_to_bids().

  • Motion capture - rigid-body kinematics from XDF motion streams via find_rigid_bodies().

  • Visualization - ERP, PSD, TFR, and topomap plots built on MNE and matplotlib.

The pipeline is designed to replicate and extend the MATLAB-based BeMoBIL pipeline in Python, sharing the same preprocessing defaults where meaningful. See Comparison with the BeMoBIL pipeline for a full comparison and migration example.

Installation#

Install the latest release from PyPI:

pip install pybemobil

To also install the JAX-accelerated AMICA backend (the default ICA method, which falls back to Picard when this is missing):

pip install "pybemobil[jamica]"

Alternatively, install the latest development version from GitHub:

pip install git+https://github.com/BeMoBIL/pybemobil.git

or install from source in editable mode, for development:

git clone https://github.com/BeMoBIL/pybemobil.git
cd pybemobil
pip install -e ".[dev]"

We recommend installing into a fresh environment, e.g. conda create -n pybemobil python=3.12.

Quick start#

from pybemobil.io import XDFLoader
from pybemobil.preproc import EEGPreprocessor

# 1. Load a multimodal XDF recording
loader = XDFLoader(
    montage="easycap-M1",
    target_sfreq=250.0,
)
recording = loader.load("sub-01_task-walk_run-01.xdf")
raw = recording.raw          # mne.io.Raw with EEG + aux channels merged

# 2. Run the full preprocessing pipeline
preprocessor = EEGPreprocessor(
    loader=loader,
    line_noise_freq="europe",   # 50 Hz + harmonics up to Nyquist
    line_noise_method="adaptive",  # ZapLine-Plus before filtering
)
raw_clean, report, metadata = preprocessor.run_raw(
    raw,
    fname_out="derivatives/pybemobil/sub-01/eeg/sub-01_task-walk_run-01_eeg.fif",
)
# writes derivatives/.../sub-01_task-walk_run-01_desc-clean_eeg.fif (+ ICA,
# report, ...) and the untouched input to sub-01/eeg/ (BIDS raw)

# raw_clean : ICA-cleaned, average-referenced, bad channels interpolated
# report    : mne.Report HTML summary (saved alongside output)
# metadata  : dict with raw_source, raw_pre_ica, ica, ic_labels, bad_ch_dict, …

Citing#

If you use pybemobil in your work, please cite it. The “Cite this repository” button on the GitHub page (generated from CITATION.cff) gives the reference in APA and BibTeX format. Every release is archived on Zenodo; to cite pybemobil in general, use the DOI 10.5281/zenodo.23480659, which always resolves to the latest version.

pybemobil is a Python implementation of the BeMoBIL pipeline, so please consider also citing:

Klug, M., Jeung, S., Wunderlich, A., Gehrke, L., Protzak, J., Djebbara, Z., Argubi-Wollesen, A., Wollesen, B., & Gramann, K. (2022). The BeMoBIL Pipeline for automated analyses of multimodal mobile brain and body imaging data. bioRxiv. https://doi.org/10.1101/2022.09.29.510051

API Reference

Guides

Project