Frequently Asked Questions#

Installation FAQ#

What Python versions does EEGPrep support?#

EEGPrep supports Python 3.10 and higher. We recommend using Python 3.11 or 3.12 for development.

How do I install EEGPrep?#

In a uv-managed project:

uv add eegprep

Published releases can also be installed with pip:

pip install eegprep

For development installation from source:

git clone https://github.com/sccn/eegprep.git
cd eegprep
uv sync --group dev

What are the system requirements?#

Operating System: Linux, macOS, or Windows
Python: 3.10 or higher
RAM: Minimum 4GB (8GB+ recommended for large datasets)
Disk Space: 500MB for installation and dependencies

Can I use EEGPrep on Windows?#

Yes, EEGPrep works on Windows. However, some optional features may require additional setup. We recommend using Windows Subsystem for Linux (WSL) for better compatibility.

What if I get dependency conflicts?#

Refresh the uv environment:

uv lock
uv sync --group dev

Or create a fresh uv environment:

rm -rf .venv
uv sync --group dev

Does EEGPrep support GPU acceleration?#

EEGPrep can leverage GPU acceleration through MNE-Python and PyTorch for ICA and other computations. Install GPU support:

uv add torch  # For GPU support
uv add "mne[cuda]"  # For MNE GPU support

Usage FAQ#

How do I load EEG data?#

EEGPrep supports multiple formats:

from pathlib import Path

import mne
from eegprep import bids_list_eeg_files, eeg_mne2eeg, pop_load_frombids, pop_loadset

# Load EEGLAB .set file
EEG = pop_loadset(Path("sample_data") / "eeglab_data.set")

# Load from a BIDS dataset
files = bids_list_eeg_files("/path/to/bids-root", subjects=["001"])
EEG = pop_load_frombids(files[0])

# Load from MNE-Python
raw = mne.io.read_raw_edf("data.edf", preload=True)
EEG = eeg_mne2eeg(raw)

What data formats are supported?#

EEGPrep supports:

EEGLAB: .set and .fdt files
BIDS: Brain Imaging Data Structure format
MNE-Python: Raw and Epochs objects
EDF: European Data Format
BrainVision: .vhdr, .vmrk, .eeg files
Neuroscan: .cnt files

How do I apply preprocessing?#

Apply preprocessing steps in sequence:

from eegprep import pop_clean_rawdata, pop_eegfiltnew, pop_loadset, pop_resample, pop_saveset

# Load data
EEG = pop_loadset("data.set")

# Apply preprocessing steps
EEG, filter_com = pop_eegfiltnew(EEG, locutoff=1, hicutoff=40, plotfreqz=False, return_com=True)
EEG, resample_com = pop_resample(EEG, 128, return_com=True)
EEG, clean_com = pop_clean_rawdata(EEG, BurstCriterion=20, return_com=True)

# Save processed data
pop_saveset(EEG, "data_processed.set")

How do I save processed data?#

Save in EEGLAB format:

eeg.save('data_processed.set')

Save in HDF5 format:

eeg.save('data_processed.h5')

Export to MNE-Python:

raw = eegprep.eeg_eeg2mne(eeg)
raw.save('data_processed_raw.fif')

Can I use EEGPrep with MNE-Python?#

Yes! EEGPrep integrates seamlessly with MNE-Python:

import eegprep
import mne

# Load with MNE
raw = mne.io.read_raw_edf('data.edf')

# Convert to EEGPrep
eeg = eegprep.eeg_mne2eeg(raw)

# Process with EEGPrep
eeg = eegprep.clean_artifacts(eeg)

# Convert back to MNE
raw = eegprep.eeg_eeg2mne(eeg)

How do I work with BIDS datasets?#

Load and process data, then export a BIDS-style folder:

from eegprep import pop_clean_rawdata, pop_exportbids, pop_loadset

EEG = pop_loadset("data.set")
EEG, clean_com = pop_clean_rawdata(EEG, BurstCriterion=20, return_com=True)
pop_exportbids(EEG, "/path/to/bids-export", subject="001", task="rest")

Performance FAQ#

Why is preprocessing slow?#

Preprocessing speed depends on:

Data size: Larger datasets take longer
Sampling rate: Higher sampling rates require more computation
Number of channels: More channels = more computation
Algorithm complexity: Some algorithms (ICA, ASR) are computationally intensive

To speed up processing:

Downsample data if appropriate
Use GPU acceleration
Process in parallel (for multiple subjects)
Use faster algorithms (e.g., ASR instead of ICA)

How much memory does EEGPrep use?#

Memory usage depends on:

Data size: Roughly 8 bytes per sample per channel
Number of channels: More channels = more memory
Sampling rate: Higher rates = more samples = more memory

Example: 64 channels, 500 Hz sampling, 1 hour of data ≈ 1.2 GB

To reduce memory usage:

Downsample data
Process shorter segments
Use memory-efficient algorithms

Can I process data in parallel?#

Yes, you can process multiple subjects in parallel:

from multiprocessing import Pool
import eegprep

def process_subject(subject_id):
    eeg = eegprep.pop_load_frombids('/bids', subject_id)
    eeg = eegprep.clean_artifacts(eeg)
    return eeg

with Pool(4) as p:
    results = p.map(process_subject, ['sub-001', 'sub-002', 'sub-003'])

How can I optimize preprocessing?#

Tips for optimization:

Choose appropriate parameters: Use defaults as starting point
Skip unnecessary steps: Only apply needed preprocessing
Use faster algorithms: ASR is faster than ICA
Downsample if appropriate: Reduces computation
Use GPU acceleration: For ICA and other algorithms
Process in batches: More efficient than one-by-one

Troubleshooting FAQ#

I get “ModuleNotFoundError: No module named ‘eegprep’”#

Solution: Install EEGPrep:

uv add eegprep

Or if developing from source:

uv sync --group dev

I get “ValueError: Data shape mismatch”#

Cause: Data dimensions don’t match expected format

Solution: Check data shape:

print(eeg.data.shape)  # Should be (channels, samples)
print(eeg.nbchan)  # Number of channels
print(eeg.pnts)  # Number of samples

I get “RuntimeError: CUDA out of memory”#

Cause: GPU memory exhausted

Solutions:

Use CPU instead:

eeg = eegprep.clean_artifacts(eeg, use_gpu=False)

Process smaller segments
Reduce batch size
Upgrade GPU memory

My data has NaN values#

Solution: Handle NaN values:

import numpy as np

# Remove NaN values
eeg.data = np.nan_to_num(eeg.data)

# Or interpolate
eeg = eegprep.eeg_interp(eeg)

How do I debug preprocessing issues?#

Enable logging:

import logging
logging.basicConfig(level=logging.DEBUG)

# Now run preprocessing with debug output
eeg = eegprep.clean_artifacts(eeg)

Check data at each step:

print(f"Original shape: {eeg.data.shape}")
eeg = eegprep.clean_flatlines(eeg)
print(f"After flatlines: {eeg.data.shape}")
eeg = eegprep.clean_channels(eeg)
print(f"After channels: {eeg.data.shape}")

Comparison FAQ#

How does EEGPrep compare to EEGLAB?#

EEGPrep:

Python-based (easier integration with modern tools)
Open-source and actively maintained
Scriptable and reproducible
Good for batch processing

EEGLAB:

MATLAB-based (established in neuroscience)
Extensive GUI
Large community and plugins
Better for interactive exploration

Recommendation: Use EEGPrep for reproducible pipelines, EEGLAB for interactive exploration.

How does EEGPrep compare to MNE-Python?#

EEGPrep:

Specialized for EEG preprocessing
EEGLAB-compatible
Comprehensive artifact removal
BIDS-native support

MNE-Python:

General neuroimaging (EEG, MEG, fMRI)
Extensive analysis tools
Large community
Better for source localization

Recommendation: Use EEGPrep for preprocessing, MNE for analysis.

How does EEGPrep compare to Fieldtrip?#

EEGPrep:

Python-based
Modern, actively maintained
Good for batch processing
BIDS support

Fieldtrip:

MATLAB-based
Established in neuroscience
Extensive documentation
Good for MEG and EEG

Recommendation: Use EEGPrep for Python workflows, Fieldtrip for MATLAB workflows.

Data Format FAQ#

What is BIDS?#

BIDS (Brain Imaging Data Structure) is a standard for organizing neuroimaging data. It ensures:

Consistency across datasets
Reproducibility
Easy sharing
Automated processing

Learn more: BIDS Specification

How do I convert data to BIDS?#

Use the BIDS converter:

from eegprep import pop_exportbids, pop_loadset

EEG = pop_loadset("data.set")
pop_exportbids(EEG, "/path/to/bids-export", subject="001", task="rest")

What’s the difference between .set and .fdt files?#

.set: EEGLAB header file (contains metadata)
.fdt: EEGLAB data file (contains actual EEG data)

Both are needed for complete EEGLAB datasets.

Can I use EEGPrep with other data formats?#

Yes, EEGPrep supports:

EDF (European Data Format)
BrainVision (.vhdr, .vmrk, .eeg)
Neuroscan (.cnt)
MNE-Python formats

Convert between formats:

import eegprep
import mne

# Load from any MNE-supported format
raw = mne.io.read_raw('data.edf')

# Convert to EEGPrep
eeg = eegprep.eeg_mne2eeg(raw)

# Save in EEGLAB format
eeg.save('data.set')

Getting Help#

Check the User Guide
Review Examples
Search GitHub Issues
Ask in GitHub Discussions
Contact the maintainers

Still have questions? Open an issue on GitHub!