BrainMaze: Brain Electrophysiology, Behavior and Dynamics Analysis Toolbox - EEG

This toolbox provides tools for processing of intracranial EEG recordings. See below and documentation for specific sections. This tool was separated from the BrainMaze toolbox to support a convenient and lightweight sharing of these tools across projects.

This project was originally developed as a part of the BEhavioral STate Analysis Toolbox (BEST) project. However, the development has transferred to the BrainMaze project.

Documentation

Documentation is available at https://bnelair.github.io/brainmaze-eeg/.

Runnable examples are in the demo/ folder (see demo/README.md).

Installation

pip install brainmaze-eeg

Plotting in brainmaze_eeg.hypnogram (plot_hypnogram, score_night(plot=True)) needs matplotlib, which is an optional extra:

pip install "brainmaze-eeg[plot]"

What’s new in 3.1.0

A minor release: no default output changes (the Janca detector with default arguments is bit-identical to 3.0.0 and to the eeg_forge reference).

• Reference baseline for the Janca detector: JancaBaseline measures the background (log-envelope mu/sd per channel) on a quiet or pre-injury recording, with gaps and constant dropouts excluded, and saves it as JSON. detect_spikes_janca(..., baseline=..., combine='reference'|'min'|'max') and JancaDetector(baseline=...) then use that fixed threshold instead of, or combined with, the local one. For channels that spike permanently: on synthetic iEEG with 1 / 3 / 5 spikes/s the local model finds 93 / 42 / 0.5 % of the spikes, the reference baseline 97 / 97 / 96 %, with no false detections. The signal-path parameters must match the baseline’s (checked), and so must the channel order when both sides have channel names (checked); the amplitude unit, gain and montage must too (not checkable; warnings flag a ×10 level mismatch on a channel and a ×3 mismatch of the montage’s background level).

• Long Janca windows on data with drops: gap_aware_stats=True computes the local statistics over valid samples only (O(n) for any window, e.g. window_s=3600 on 24 h) and never detects on samples left out of them (dropouts and their edges); GapAwareSpikeDetector passes its gap mask so filled samples never enter them.

See Reference baseline in the spike detectors README for when to use it, what must match, and the limitations.

What’s new in 3.0.0

brainmaze-eeg 3.0.0 is a major release: default outputs change (list below). It requires brainmaze-utils>=3.0.0, which resamples correctly at every sampling rate and DC level and provides brainmaze_utils.gaps (its numerical changes are listed on the utils changes page). Full list of merged pull requests: release notes.

New

• detect_spikes_janca / JancaDetector (Janca et al. 2015, eeg_forge formulation, with presets 'spike' and 'ripple'; the ripple preset is not validated on real ripples) and GapAwareSpikeDetector, a wrapper that makes any spike detector safe for data with NaN gaps or constant-value dropouts and reports the valid time per channel. In 1.0.0 the package had only SpikeDetectorHilbert and detect_spikes_barkmeier. The raw detectors require finite input. See the Spike detectors page and the detailed README.

• WaveDetector features WAVE_SLOPE_MEDIAN and ANALYSABLE_RATE (appended at the end, so the 1.0.0 feature names and positions are unchanged), the trough='paper' mode (Carvalho et al. 2024 Methods), NaN gaps handled, and 7.5-9x faster. The same values, names = detector(x) interface as the other feature extractors. See the WaveDetector and slow-wave project pages.

• Out-of-distribution epochs in the sleep classifiers (brainmaze_eeg.classifiers) are labelled 'UNKNOWN' (NaN probabilities) instead of getting a confident label. The floor is not an artifact detector. See the Classifiers page.

• Demos for all three: demo/.

Changes in default output, and the way back

How to contribute

The project has 2 main protected branches main that contains official software releases and dev that contains the latest feature implementations shared with developers. To implement a new feature a new branch should be created from the dev branch with name pattern of developer_identifier/feature_name.

After the feature is implemented, a pull request can be created to merge the feature branch into the dev branch with. Pull requests need to be reviewed by a maintainer.

pip install -e ".[docs]"

pip install -r docs_src/requirements.txt

sphinx-build -b html docs_src/source docs

License

This software is licensed under BSD-3Clause license. For details see the LICENSE file in the root directory of this project.

Acknowledgment

This code was developed and originally published for the first time by (Mivalt 2022, and Sladky 2022). Additionally, codes related to individual projects available in this repository are stated below. When using this toolbox, we appreciate you citing the papers related to the utilized functionality. Please, see the sections below for references to individual submodules.

F. Mivalt et V. Kremen et al., “Electrical brain stimulation and continuous behavioral state tracking in ambulatory humans,” J. Neural Eng., vol. 19, no. 1, p. 016019, Feb. 2022, doi: 10.1088/1741-2552/ac4bfd.

V. Sladky et al., “Distributed brain co-processor for tracking spikes, seizures and behaviour during electrical brain stimulation,” Brain Commun., vol. 4, no. 3, May 2022, doi: 10.1093/braincomms/fcac115.

Funding

Individual sections of this code were developed under different projects including:

• NIH Brain Initiative UH2&3 NS095495 - Neurophysiologically-Based Brain State Tracking & Modulation in Focal Epilepsy,

• NIH U01-NS128612 - An Ecosystem of Technology and Protocols for Adaptive Neuromodulation Research in Humans,

• DARPA - HR0011-20-2-0028 Manipulating and Optimizing Brain Rhythms for Enhancement of Sleep (Morpheus).

• FEKT-K-22-7649 realized within the project Quality Internal Grants of the Brno University of Technology (KInG BUT), Reg. No. CZ.02.2.69/0.0/0.0/19_073/0016948, which is financed from the OP RDE.