Skip to content

Latest commit

 

History

History
161 lines (122 loc) · 5.28 KB

README.md

File metadata and controls

161 lines (122 loc) · 5.28 KB

iEEG Implant Reconstruction Pipeline

A Python-based pipeline for reconstructing intracranial EEG (iEEG) electrode locations from post-implant CT and pre-implant MRI scans.

Overview

This pipeline provides tools for:

  • Extracting electrode coordinates from post-implant CT scans
  • Co-registering CT and MRI images
  • Mapping electrodes to anatomical regions
  • Quality assurance visualization

Prerequisites

Required Software

  • FSL (FMRIB Software Library)
  • ITK-SNAP
  • FreeSurfer
  • Python 3.x with required packages (see requirements.txt)

System Requirements

  • Operating System: Linux/Unix (recommended), macOS, or Windows with Unix subsystem
  • RAM: 8GB minimum, 16GB recommended
  • Storage: At least 10GB free space for processing

Installation

There are two ways to install this package:

  1. Direct installation from GitHub:

    pip install git+https://github.com/n-sinha/ieeg_recon.git

    For development installation (includes testing tools):

    pip install "git+https://github.com/n-sinha/ieeg_recon.git#egg=ieeg_recon[dev]"

  2. Local development installation:

    # Clone this repository
git clone https://github.com/n-sinha/ieeg_recon.git
cd ieeg_recon

# Install in editable mode with development dependencies
pip install -e ".[dev]"

  3. Create and configure your .env file:

    # FSL Configuration
FSL_DIR=/path/to/fsl
FSL_OUTPUT_TYPE=NIFTI_GZ

# ITK-SNAP Configuration
ITKSNAP_DIR=/path/to/ITK-SNAP

# FreeSurfer Configuration
FREESURFER_HOME=/path/to/freesurfer
SUBJECTS_DIR=/path/to/subjects_dir

    Example of a configured .env file:

    # FSL Configuration
FSL_DIR=/usr/local/fsl
FSL_OUTPUT_TYPE=NIFTI_GZ

# ITK-SNAP Configuration
ITKSNAP_DIR=/Applications/ITK-SNAP.app/Contents/bin

# FreeSurfer Configuration
FREESURFER_HOME=/Applications/freesurfer/7.3.2
SUBJECTS_DIR=/Applications/freesurfer/7.3.2/subjects

After installation, you can import the package in Python:

from ieeg_recon import IEEGRecon, run_pipeline

Usage

The pipeline can be run using the command-line interface:

python run_ieeg_recon.py --t1 /path/to/t1.nii.gz \
                        --ct /path/to/ct.nii.gz \
                        --elec /path/to/electrodes.txt \
                        --output-dir /path/to/output \
                        --freesurfer-dir /path/to/freesurfer_dir

Command Line Arguments

Required:

  • --t1: Path to pre-implant T1 MRI
  • --ct: Path to post-implant CT
  • --elec: Path to electrode coordinates file
  • --output-dir: Output directory path

Optional:

  • --freesurfer-dir: Path to FreeSurfer directory
  • --env-path: Path to environment file (default: '.env')
  • --modules: Modules to run (comma-separated, e.g., "1,2,3,4", default: "1,2,3,4")
  • --skip-existing: Skip processing if output files exist
  • --reg-type: Registration type ('gc', 'g', 'gc_noCTthereshold', default: 'gc_noCTthereshold')
  • --qa-viewer: Quality assurance viewer type ('freeview', 'freeview_snapshot', 'niplot', 'itksnap', 'none', default: 'niplot')

Pipeline Modules

Module 1: Electrode Coordinate Export

Exports electrode coordinates from post-implant CT in voxel and native space.

Module 2: Image Registration

Performs CT-MRI co-registration with options for:

  • Greedy registration with image centering ('gc')
  • FLIRT registration fine-tuned with greedy ('g')
  • Greedy registration without CT thresholding ('gc_noCTthereshold')

Module 3: ROI Mapping

Maps electrodes to anatomical regions using an atlas and provides quality assurance visualization.

Module 4: MNI Space Transformation

Transforms electrode coordinates to MNI305 and MNI152 standard spaces for cross-subject comparisons and group analyses.

Output Structure

output_dir/
├── module1/
│   ├── electrode_names.txt       # List of electrode names
│   ├── electrodes_inCTvox.txt   # Electrode coordinates in CT voxel space
│   └── electrodes_inCTmm.txt    # Electrode coordinates in CT millimeter space
├── module2/
│   ├── ct_to_mri.nii.gz         # Registered CT to MRI image
│   ├── electrodes_inMRI.nii.gz  # Electrode positions in MRI space
│   └── QA_registration.png      # Quality assurance visualization
└── module3/
    ├── electrodes2ROI.csv       # Mapping of electrodes to regions of interest
    └── electrode_visualization.html  # Interactive 3D visualization

Quality Assurance

The pipeline includes comprehensive quality assurance tools:

  • Interactive 3D visualization of electrode positions
  • Multiple viewing options (hemisphere visibility, electrode size, label toggle)
  • Registration quality checks
  • Electrode placement verification

Citation

If you use this software in your research, please cite:

Lucas A, Scheid BH, Pattnaik AR, Gallagher R, Mojena M, Tranquille A, Prager B, Gleichgerrcht E, Gong R, Litt B, Davis KA, Das S, Stein JM, Sinha N. iEEG-recon: A fast and scalable pipeline for accurate reconstruction of intracranial electrodes and implantable devices. Epilepsia. 2024 Mar;65(3):817-829. doi: 10.1111/epi.17863.

Support

For bug reports and feature requests, please use the GitHub Issue Tracker.