ECoGSTNDecoding

ECoG-based STN Decoding using Deep Learning and Diffusion Models

Overview

Next-generation neurotechnologies aim to decode brain activity to guide assistive brain-computer interfaces (BCIs) and closed-loop neuromodulation therapies. These applications often rely on sensing electrophysiological signals from deep brain targets (e.g., subthalamic nucleus, globus pallidus internus, thalamus), which are small and deeply located structures associated with distinct disease signatures.

However, extracting meaningful information from these targets is challenging due to:

Low signal-to-noise ratio (SNR)
Stimulation and physiological artifacts
Recording failures or incomplete data

To address these limitations, we propose a hybrid decoding framework that leverages cortical electrocorticography (ECoG) signals to reconstruct deep brain activity using:

CtxNet – a deep spectral model for decoding subcortical activity
DDPM – a generative diffusion model for raw signal reconstruction

Our approach has been validated on 723 hours of recordings from 49 patients, spanning:

Multiple diseases: Parkinson’s disease, dystonia, Tourette syndrome
Behavioral states: rest, movement, sleep
Deep brain targets: STN, GPi, thalamus

Key Contributions

💡 CtxNet: Architecture for modeling spectral features of cortical signals
🌀 DDPM: Denoising Diffusion Probabilistic Model for signal imputation
🧠 Clinical utility: Robust decoding during DBS lead failures for sleep staging and movement detection
🔮 Future-ready: Enabling deep brain state prediction without relying on invasive DBS signals

Visual Summary

System Requirements

Software Dependencies

This software has been tested on the following system configuration:

Python: 3.10.18 or higher
Operating System: Windows 10/11, Linux (Ubuntu 20.04+), or macOS 10.15+
CUDA: 12.6 or higher (for GPU acceleration)

Required Python Packages

torch==2.8.0+cu126 (or compatible PyTorch version with CUDA support)
numpy==2.1.2
scipy==1.15.3
pandas==2.3.1
matplotlib==3.10.5
scikit-learn==1.7.1
mne==1.10.1
jupyter==1.1.1
notebook==7.4.5
ipython==7.34.0
tqdm==4.67.1
pillow==11.0.0

Hardware Requirements

Minimum Requirements:

CPU: Multi-core processor (4+ cores recommended)
RAM: 16 GB
GPU: NVIDIA GPU with CUDA support (8+ GB VRAM recommended)
Storage: 10 GB free disk space

Recommended Configuration (used for testing):

CPU: 48 physical cores (96 logical cores)
RAM: 128 GB
GPU: NVIDIA GPU with CUDA 12.6+ (tested with single GPU)
Storage: 50+ GB for large datasets

Operating Systems Tested

Windows 10/11 (AMD64)

Installation

Step 1: Clone the Repository

git clone https://github.com/zixiao-yin/ECoGSTNDecoding.git
cd ECoGSTNDecoding

Step 2: Create a Virtual Environment (Recommended)

# Using conda
conda create -n ecog_stn python=3.10
conda activate ecog_stn

# Or using venv
python -m venv ecog_stn_env
source ecog_stn_env/bin/activate  # On Windows: ecog_stn_env\Scripts\activate

Step 3: Install Dependencies

# Install PyTorch with CUDA support (adjust for your CUDA version)
# Visit https://pytorch.org/get-started/locally/ for the appropriate command
pip install torch==2.8.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

# Install other dependencies
pip install numpy==2.1.2 scipy==1.15.3 pandas==2.3.1 matplotlib==3.10.5
pip install scikit-learn==1.7.1 mne==1.10.1 tqdm==4.67.1 pillow==11.0.0
pip install jupyter notebook ipython

# Or install all dependencies from requirements file
pip install -r requirements.txt

Demo

Quick Start with Demo Data

We provide a small demonstration dataset to test the software installation and basic functionality.

Step 1: Download Demo Data

# Demo data is available here at [10.6084/m9.figshare.30472508](https://figshare.com/articles/dataset/ecogstn_decoding_demo_dataset/30472508)

Step 2: Run Demo Notebooks

# Launch Jupyter Notebook
jupyter notebook

# Navigate to and open:
# 1. "CtxNet Implementation - demo.ipynb"
# 2. "DDPM Implementation - demo.ipynb"

Expected Output

CtxNet Demo: Should produce spectral decoding results with correlation metrics and visualization plots
DDPM Demo: Should generate reconstructed waveforms and comparison with ground truth

Expected Runtime

CtxNet Demo: ~20-30 minutes on a GPU
DDPM Demo: ~40-60 minutes on a GPU

Instructions for Use

Running the Software on Your Own Data

Data Format Requirements

The software expects input data in the following format:

ECoG signals: NumPy array format (.npy) or MNE-Python Raw objects
Shape: (n_channels, n_timepoints) or (n_epochs, n_channels, n_timepoints)
Deep brain signals (optional, for training): Same format as ECoG

Step 1: Prepare Your Data

import numpy as np
import mne

# Load your ECoG data
ecog_data = np.load('your_ecog_data.npy')  # Shape: (n_channels, n_timepoints)
stn_data = np.load('your_stn_data.npy')    # Shape: (n_channels, n_timepoints)

# Or use MNE format
raw_ecog = mne.io.read_raw_fif('your_ecog_data.fif')

Step 2: CtxNet Training

Open and follow the notebook:

"1. CtxNet Implementation for Spectral Feature Modeling/CtxNet Implementation - Architecture & Training & Validation Pipeline.ipynb"

Key steps:

Load your ECoG and STN data
Configure model hyperparameters
Train the CtxNet model
Evaluate decoding performance
Save trained model

Step 3: DDPM Signal Reconstruction

Open and follow the notebook:

"2. DDPM Implementation for Raw Signal Reconstruction/DDPM Implementation - Training Base Model.ipynb"

Key steps:

Load preprocessed data
Configure diffusion model parameters
Train the DDPM model
Generate reconstructed signals
Evaluate reconstruction quality

Step 4: Transfer Learning (Optional)

For adapting models to new subjects or conditions:

CtxNet: CtxNet Implementation - Transfer Learning.ipynb
DDPM: DDPM Implementation - Transfer Learning.ipynb

Expected Outputs

CtxNet: Decoded spectral features, correlation metrics, prediction accuracy
DDPM: Reconstructed waveforms, signal quality metrics, visualization plots

Repository Structure