Note
Go to the end to download the full example code.
Comprehensive Preprocessing with MNE-based Classes#
This example demonstrates the various preprocessing classes available in Braindecode that wrap MNE-Python functionality. These classes provide a convenient and type-safe way to preprocess EEG data.
# Authors: Bruno Aristimunha <b.aristimunha@gmail.com>
#
# License: BSD (3-clause)
import mne
from braindecode.datasets import MOABBDataset
from braindecode.preprocessing import (
Anonymize,
ApplyHilbert,
Crop,
Filter,
Pick,
Resample,
SetEEGReference,
SetMontage,
preprocess,
)
Load a sample dataset#
We’ll use a small MOABB dataset for demonstration
dataset = MOABBDataset(dataset_name="BNCI2014_001", subject_ids=[1])
0%| | 0.00/42.8M [00:00<?, ?B/s]
0%| | 8.19k/42.8M [00:00<08:48, 81.0kB/s]
0%| | 56.3k/42.8M [00:00<02:18, 309kB/s]
0%| | 121k/42.8M [00:00<01:34, 454kB/s]
0%|▏ | 176k/42.8M [00:00<01:27, 486kB/s]
1%|▏ | 264k/42.8M [00:00<01:08, 618kB/s]
1%|▎ | 369k/42.8M [00:00<00:56, 752kB/s]
1%|▍ | 444k/42.8M [00:00<00:56, 746kB/s]
1%|▌ | 600k/42.8M [00:00<00:42, 988kB/s]
2%|▋ | 753k/42.8M [00:00<00:36, 1.14MB/s]
2%|▊ | 1.00M/42.8M [00:01<00:27, 1.53MB/s]
3%|█ | 1.24M/42.8M [00:01<00:23, 1.77MB/s]
4%|█▎ | 1.58M/42.8M [00:01<00:18, 2.22MB/s]
5%|█▋ | 1.93M/42.8M [00:01<00:15, 2.58MB/s]
6%|██▏ | 2.47M/42.8M [00:01<00:11, 3.39MB/s]
7%|██▋ | 3.04M/42.8M [00:01<00:09, 4.03MB/s]
9%|███▎ | 3.90M/42.8M [00:01<00:07, 5.33MB/s]
11%|████▏ | 4.89M/42.8M [00:01<00:05, 6.59MB/s]
15%|█████▍ | 6.26M/42.8M [00:01<00:04, 8.61MB/s]
18%|██████▊ | 7.91M/42.8M [00:01<00:03, 10.8MB/s]
24%|████████▋ | 10.1M/42.8M [00:02<00:02, 13.9MB/s]
30%|███████████▏ | 12.9M/42.8M [00:02<00:01, 17.9MB/s]
38%|██████████████▏ | 16.4M/42.8M [00:02<00:01, 22.7MB/s]
49%|██████████████████▏ | 21.0M/42.8M [00:02<00:00, 29.3MB/s]
60%|██████████████████████▏ | 25.6M/42.8M [00:02<00:00, 33.9MB/s]
72%|██████████████████████████▋ | 30.9M/42.8M [00:02<00:00, 38.6MB/s]
86%|███████████████████████████████▉ | 36.9M/42.8M [00:02<00:00, 44.6MB/s]
0%| | 0.00/42.8M [00:00<?, ?B/s]
100%|██████████████████████████████████████| 42.8M/42.8M [00:00<00:00, 153GB/s]
0%| | 0.00/43.8M [00:00<?, ?B/s]
0%| | 8.19k/43.8M [00:00<09:21, 78.0kB/s]
0%| | 56.3k/43.8M [00:00<02:26, 299kB/s]
0%| | 128k/43.8M [00:00<01:32, 470kB/s]
0%|▏ | 209k/43.8M [00:00<01:14, 585kB/s]
1%|▎ | 321k/43.8M [00:00<00:57, 752kB/s]
1%|▍ | 457k/43.8M [00:00<00:46, 931kB/s]
1%|▌ | 608k/43.8M [00:00<00:39, 1.09MB/s]
2%|▋ | 833k/43.8M [00:00<00:30, 1.42MB/s]
2%|▉ | 1.06M/43.8M [00:00<00:25, 1.65MB/s]
3%|█▏ | 1.43M/43.8M [00:01<00:19, 2.21MB/s]
4%|█▍ | 1.74M/43.8M [00:01<00:17, 2.43MB/s]
5%|█▉ | 2.31M/43.8M [00:01<00:12, 3.31MB/s]
7%|██▍ | 2.94M/43.8M [00:01<00:09, 4.09MB/s]
9%|███▎ | 3.95M/43.8M [00:01<00:06, 5.74MB/s]
11%|████▏ | 4.94M/43.8M [00:01<00:05, 6.79MB/s]
16%|█████▊ | 6.82M/43.8M [00:01<00:03, 10.1MB/s]
19%|███████▏ | 8.48M/43.8M [00:01<00:03, 11.7MB/s]
27%|██████████ | 11.9M/43.8M [00:01<00:01, 17.9MB/s]
34%|████████████▋ | 15.0M/43.8M [00:02<00:01, 21.2MB/s]
46%|█████████████████▏ | 20.4M/43.8M [00:02<00:00, 29.8MB/s]
60%|██████████████████████▏ | 26.2M/43.8M [00:02<00:00, 36.9MB/s]
72%|██████████████████████████▍ | 31.3M/43.8M [00:02<00:00, 40.0MB/s]
86%|███████████████████████████████▉ | 37.8M/43.8M [00:02<00:00, 45.5MB/s]
0%| | 0.00/43.8M [00:00<?, ?B/s]
100%|██████████████████████████████████████| 43.8M/43.8M [00:00<00:00, 186GB/s]
Signal Processing#
Apply common signal processing operations
# 1. Resample to reduce computational load
print(f"Original sampling frequency: {dataset.datasets[0].raw.info['sfreq']} Hz")
preprocessors_signal = [
Resample(sfreq=100), # Downsample to 100 Hz
]
preprocess(dataset, preprocessors_signal)
print(f"After resampling: {dataset.datasets[0].raw.info['sfreq']} Hz")
# 2. Remove power line noise and apply bandpass filter
preprocessors_filtering = [
Filter(l_freq=4, h_freq=30), # Bandpass filter 4-30 Hz
]
preprocess(dataset, preprocessors_filtering)
print("Applied bandpass filter 4-30 Hz")
Original sampling frequency: 250.0 Hz
After resampling: 100.0 Hz
Applied bandpass filter 4-30 Hz
Channel Management#
Select and manipulate channels
# 3. Pick only EEG channels
preprocessors_channels = [
Pick(picks="eeg"), # Select only EEG channels
]
print(f"Channels before pick: {len(dataset.datasets[0].raw.ch_names)}")
preprocess(dataset, preprocessors_channels)
print(f"Channels after pick: {len(dataset.datasets[0].raw.ch_names)}")
# 4. Rename channels (example - just for demonstration)
original_names = dataset.datasets[0].raw.ch_names[:3]
print(f"Original channel names (first 3): {original_names}")
# Note: We won't actually rename to avoid breaking the example,
# but this is how you would do it:
# preprocessors_rename = [
# RenameChannels(mapping={'C3': 'C3_renamed', 'C4': 'C4_renamed'}),
# ]
# preprocess(dataset, preprocessors_rename)
Channels before pick: 26
Channels after pick: 22
Original channel names (first 3): ['Fz', 'FC3', 'FC1']
Reference & Montage#
Set reference and channel positions
# 5. Set EEG reference to average
preprocessors_reference = [
SetEEGReference(ref_channels="average"),
]
preprocess(dataset, preprocessors_reference)
print("Set EEG reference to average")
# 6. Set montage for proper channel positions
montage = mne.channels.make_standard_montage("standard_1020")
preprocessors_montage = [
SetMontage(montage=montage, match_case=False, on_missing="ignore"),
]
preprocess(dataset, preprocessors_montage)
print(
f"Set montage, number of positions: {len(dataset.datasets[0].raw.get_montage().get_positions()['ch_pos'])}"
)
Set EEG reference to average
Set montage, number of positions: 22
Data Transformation#
Apply transformations to the data
# 7. Crop data to specific time range
preprocessors_crop = [
Crop(tmin=0, tmax=60), # Keep only first 60 seconds
]
print(f"Data duration before crop: {dataset.datasets[0].raw.times[-1]:.1f} s")
preprocess(dataset, preprocessors_crop)
print(f"Data duration after crop: {dataset.datasets[0].raw.times[-1]:.1f} s")
Data duration before crop: 386.9 s
Data duration after crop: 60.0 s
Metadata & Configuration#
Modify metadata and configuration
# 8. Anonymize measurement information
preprocessors_anonymize = [
Anonymize(),
]
preprocess(dataset, preprocessors_anonymize)
print("Anonymized measurement information")
Anonymized measurement information
Advanced: Envelope Extraction#
Extract signal envelope using Hilbert transform
# 9. Compute envelope (useful for some analyses)
# Note: This modifies the data, so use carefully
preprocessors_envelope = [
ApplyHilbert(envelope=True),
]
preprocess(dataset, preprocessors_envelope)
print("Computed signal envelope")
Computed signal envelope
Combining Multiple Preprocessing Steps#
You can combine multiple preprocessing steps in a single pipeline
print("\n" + "=" * 60)
print("Complete Preprocessing Pipeline Example")
print("=" * 60)
# Reload dataset for complete pipeline demonstration
dataset_complete = MOABBDataset(dataset_name="BNCI2014_001", subject_ids=[1])
# Set montage first (needed for interpolation)
montage = mne.channels.make_standard_montage("standard_1020")
complete_pipeline = [
# 1. Set montage
SetMontage(montage=montage, match_case=False, on_missing="ignore"),
# 2. Set reference
SetEEGReference(ref_channels="average"),
# 3. Bandpass filter
Filter(l_freq=4, h_freq=30),
# 4. Downsample
Resample(sfreq=100),
# 5. Select only EEG channels
Pick(picks="eeg"),
# 6. Crop to region of interest
Crop(tmin=0, tmax=60),
# 7. Anonymize
Anonymize(),
]
print(
f"Original: {dataset_complete.datasets[0].raw.info['sfreq']} Hz, "
f"{dataset_complete.datasets[0].raw.times[-1]:.1f} s, "
f"{len(dataset_complete.datasets[0].raw.ch_names)} channels"
)
preprocess(dataset_complete, complete_pipeline)
print(
f"After preprocessing: {dataset_complete.datasets[0].raw.info['sfreq']} Hz, "
f"{dataset_complete.datasets[0].raw.times[-1]:.1f} s, "
f"{len(dataset_complete.datasets[0].raw.ch_names)} channels"
)
print("\nPreprocessing complete!")
============================================================
Complete Preprocessing Pipeline Example
============================================================
Original: 250.0 Hz, 386.9 s, 26 channels
After preprocessing: 100.0 Hz, 60.0 s, 22 channels
Preprocessing complete!
Summary#
Braindecode provides 45 preprocessing classes that wrap MNE-Python functionality:
Signal Processing: Resample, Filter, NotchFilter, SavgolFilter, ApplyHilbert, Rescale, OversampledTemporalProjection
Channel Management: Pick, PickChannels, PickTypes, DropChannels, AddChannels, CombineChannels, RenameChannels, ReorderChannels, SetChannelTypes, InterpolateBads, InterpolateTo, InterpolateBridgedElectrodes, ComputeBridgedElectrodes, EqualizeChannels
Reference & Montage: SetEEGReference, AddReferenceChannels, SetMontage
SSP Projections: AddProj, ApplyProj, DelProj
Data Transformation: Crop, CropByAnnotations, ComputeCurrentSourceDensity, FixStimArtifact, MaxwellFilter, RealignRaw, RegressArtifact
Artifact Detection & Annotation: AnnotateAmplitude, AnnotateBreak, AnnotateMovement, AnnotateMuscleZscore, AnnotateNan
Metadata & Configuration: Anonymize, SetAnnotations, SetMeasDate, AddEvents, FixMagCoilTypes, ApplyGradientCompensation
See the API documentation for details on each class and their parameters.
Total running time of the script: (0 minutes 21.835 seconds)
Estimated memory usage: 855 MB
Run this example
