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

Migrating to brainmaze-eeg-models

Change the import; the function names, arguments and outputs are the same:

# before (brainmaze-torch)
from brainmaze_torch.seizure_detection import predict_channel_seizure_probability
# after (brainmaze-eeg-models)
from brainmaze_eeg_models.seizure import predict_channel_seizure_probability

t, p = predict_channel_seizure_probability(x, fs, model='modelA')   # unchanged call

One 0.2.0 pattern now raises ValueError (loudly, never silently): loading a model and then asking for the GPU per call,

m = load_trained_model('modelA')                                # 0.2.0: always a CPU model
predict_channel_seizure_probability(x, fs, m, use_cuda=True)    # 0.2.0: ran on cuda:0; now ValueError

An ONNX Runtime session cannot move between devices. Choose the device when loading, or pass the model name:

m = load_trained_model('modelA', device='cuda', cuda_device_id=0)   # GPU k: cuda_device_id=k
predict_channel_seizure_probability(x, fs, m)
# or
predict_channel_seizure_probability(x, fs, 'modelA', use_cuda=True, cuda_number=0)

Numbers: the ONNX models are exported from the 0.2.0 weights and give the same probabilities as PyTorch to float32 rounding (typically ~1e-6, at most ~2e-5), with identical NaN masks; the golden tests of this repository (outputs of the published 0.1.1 code, tolerance 1e-4) pass unchanged on the shim. For a GPU, install onnxruntime-gpu in place of onnxruntime as described in the brainmaze-eeg-models README.

Silencing the warning while you migrate (better: migrate):

import warnings
warnings.filterwarnings("ignore", message="brainmaze-torch is retired", category=FutureWarning)
import brainmaze_torch.seizure_detection          # the filter must be set before the first import

Installation

pip install brainmaze-eeg-models        # recommended: the successor
pip install -U brainmaze-torch          # only to keep old code running (0.3.0 shim, no torch)

Requirements: Python >= 3.10 and brainmaze-eeg-models >= 0.1.0 (which brings numpy, scipy, onnxruntime and brainmaze-utils). Upgrading from 0.2.0 removes the bundled .pt weights but leaves an installed torch in place; uninstall it yourself if nothing else needs it. Projects that need the PyTorch implementation itself can pin brainmaze-torch==0.2.0 (torch >= 2.3); it stays on PyPI but is not maintained.

History

• 0.3.0 (final): compatibility shim over brainmaze-eeg-models (see above); torch and the .pt models removed; the repository is archived after this release.

• 0.2.0: NaN for unevaluated time, full coverage of the recording, stricter input validation, dependencies reduced to numpy, scipy, torch >= 2.3. Details: RELEASING.md.

This project was originally developed as a part of the BEhavioral STate Analysis Toolbox (BEST) project; development then moved to the BrainMaze project and, for the trained models, to brainmaze-eeg-models.

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 these models (now in brainmaze-eeg-models), 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 Techmology 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.