AutoClean EEG2Source

Transform your EEG data into source-localized representations using the Desikan-Killiany atlas regions with ease and efficiency

Get Started View on GitHub

Overview

AutoClean EEG2Source is a specialized Python package designed for neuroscientists and researchers working with high-density EEG data. It provides a robust, memory-efficient pipeline for converting EEG epochs to source-localized data using brain regions from the Desikan-Killiany atlas.

Powered by MNE-Python: Our package builds upon the excellent MNE-Python framework, the leading open-source solution for analyzing EEG, MEG, and other neurophysiological data. We gratefully acknowledge the MNE development team for creating this exceptional foundation.

Whether you're analyzing individual recordings or processing large datasets, AutoClean EEG2Source offers the tools you need to transform scalp-level electrical activity into meaningful brain source estimations, with automatic error recovery, parallel processing, and GPU acceleration capabilities.

Designed with beginners in mind, the package features straightforward command-line and Python interfaces, detailed documentation, and optimized performance even on modest hardware.

PyPI Package GitHub Repository MNE-Python

EEG Source Localization

Source localization illustration (image from MNE-Python)

Key Features

Source Localization

Convert EEG epochs to source-localized data with 68 regions from the Desikan-Killiany atlas.

Performance Optimized

Parallel processing, GPU acceleration, and memory-efficient operations for handling large datasets.

Robust Processing

Automatic error recovery mechanisms to handle common issues with EEG data.

Easy to Use

Simple command-line interface and Python API designed for both beginners and experts.

EEGLAB Compatible

Works with standard EEGLAB .set/.fdt file formats, maintaining workflow compatibility.

Benchmarking Tools

Built-in performance measurements to help optimize processing for your specific hardware.

Installation

AutoClean EEG2Source can be installed using UV or pip. UV is recommended for its faster installation speed and better dependency resolution.

# Install UV if you don't have it
pip install uv

# Install AutoClean EEG2Source with UV
uv pip install autoclean-eeg2source

For development installation:

# Clone the repository
git clone https://github.com/cincibrainlab/autoclean-eeg2source.git
cd autoclean-eeg2source

# Install in development mode with UV
uv pip install -e .

# With development dependencies
uv pip install -e ".[dev]"
# Install with pip
pip install autoclean-eeg2source
# Clone the repository
git clone https://github.com/cincibrainlab/autoclean-eeg2source.git
cd autoclean-eeg2source

# Install from source
pip install .

# Or with UV (recommended)
uv pip install .

System Requirements

Minimum Requirements
  • Python 3.9 or higher
  • 8GB RAM
  • 4 CPU cores
  • 10GB free disk space
Recommended
  • Python 3.10 or higher
  • 16GB+ RAM
  • 8+ CPU cores
  • 50GB+ free disk space
  • NVIDIA GPU with CUDA support (for acceleration)

Quickstart Guide

Check your data

First, check information about your EEG file:

autoclean-eeg2source info path/to/your/eegfile.set

Validate your data

Ensure your file is suitable for processing:

autoclean-eeg2source validate path/to/your/eegfile.set --check-montage

Process your data

Run the source localization process:

autoclean-eeg2source process path/to/your/eegfile.set --output-dir ./output

Check the results

Your source-localized data is now available in the output directory:

  • *_dk_regions.set - Source-localized data with 68 DK atlas regions
  • *_region_info.csv - Metadata for brain regions

Python API Example

from autoclean_eeg2source import SequentialProcessor, MemoryManager

# Initialize components
memory_manager = MemoryManager(max_memory_gb=4)
processor = SequentialProcessor(
    memory_manager=memory_manager,
    montage="GSN-HydroCel-129",
    resample_freq=250
)

# Process a file
result = processor.process_file("input.set", "./output")

if result['status'] == 'success':
    print(f"Output saved to: {result['output_file']}")
else:
    print(f"Processing failed: {result['error']}")

Real-World Examples

Example 1: Processing an EEG Study with 30 Participants

Imagine you have completed an EEG study with 30 participants, each with preprocessed and epoched data in EEGLAB format. You now want to conduct source-level analysis using the Desikan-Killiany atlas regions.

Step 1: Validate all files in batch
autoclean-eeg2source validate /path/to/study/data --recursive --check-montage --save-validation
Step 2: Process files with parallel processing and memory optimization
autoclean-eeg2source process /path/to/study/data \
  --output-dir ./source_data \
  --parallel --n-jobs 8 \
  --optimized-memory --max-memory 16.0 \
  --recursive \
  --robust \
  --save-summary
Step 3: Analyze and visualize the results

Once processed, you can load the source-localized data in EEGLAB or use your own analysis scripts to work with the 68 brain regions. Here's a simple Python example to get you started:

import mne
import pandas as pd
import matplotlib.pyplot as plt

# Load source-localized data
epochs = mne.io.read_epochs_eeglab('./source_data/sub01_dk_regions.set')

# Load region metadata
regions = pd.read_csv('./source_data/sub01_region_info.csv')

# Plot the average activity across all epochs for a specific region
region_name = 'bankssts-lh'  # Example region
region_idx = regions[regions['names'] == region_name].index[0]

plt.figure(figsize=(10, 5))
plt.plot(epochs.times, epochs.get_data().mean(axis=0)[region_idx])
plt.title(f'Average activity in {region_name}')
plt.xlabel('Time (s)')
plt.ylabel('Source strength (A·m)')
plt.show()

Example 2: Optimizing Performance with Benchmarking

Before processing a large dataset, it's helpful to determine which processing method will be most efficient for your specific hardware configuration.

Step 1: Run the benchmark
autoclean-eeg2source benchmark /path/to/sample/data --test-all --max-files 2
Step 2: Process with the optimal method

Based on the benchmark results, choose the most efficient processor for your system. For example, if the GPU processor showed the best performance:

autoclean-eeg2source process /path/to/study/data \
  --output-dir ./source_data \
  --gpu --gpu-backend auto \
  --enable-cache \
  --recursive

Alternatively, if parallel processing was faster:

autoclean-eeg2source process /path/to/study/data \
  --output-dir ./source_data \
  --parallel --n-jobs -1 \
  --batch-processing \
  --enable-cache \
  --recursive

Development Roadmap

Important Note

Current Development: We are actively working on several important enhancements to make AutoClean EEG2Source even more versatile and user-friendly:

  1. Continuous Data Support: While the current version works with epoched data, we're developing support for continuous EEG data processing, removing the requirement for pre-epoched data.
  2. Configuration File System: We're implementing a YAML-based configuration system to easily customize processing parameters without command-line arguments, making it simpler to use with custom datasets and research requirements.
  3. Enhanced Validation: Advanced data quality assessment tools to ensure your data meets requirements for reliable source localization.

These features are part of our commitment to making advanced neuroimaging techniques accessible to researchers of all experience levels. Stay updated by following our GitHub repository.

Planned Features
  • Continuous EEG data processing
  • YAML configuration file support
  • Improved automatic montage detection
  • Expanded source visualization tools
  • Support for additional source reconstruction methods
Get Involved

We welcome contributions and feedback from the community! There are several ways to get involved:

  • Report bugs or suggest features through GitHub Issues
  • Contribute code via pull requests
  • Share your use cases to help us improve the tool
  • Cite our work in your publications

For questions and support, please reach out through the GitHub repository or contact the authors directly.

Get Started with AutoClean EEG2Source

Acknowledgments

MNE-Python Logo

MNE-Python Project

AutoClean EEG2Source is built upon the MNE-Python ecosystem and utilizes many of its powerful source localization algorithms. We are deeply grateful to the MNE development team and the broader MNE community for creating and maintaining this essential neuroimaging toolkit.

When using AutoClean EEG2Source, please also cite the MNE-Python publications: