Skip to content

1. Setup and usage

Jump to bottom
Kevin Tan edited this page Apr 10, 2024 · 13 revisions

ElectroCUDA is intended for workstations & HPC nodes (gaming PCs might suffice). For better performance, run Matlab without its IDE matlab -nodisplay

Development environment

Default electroCUDA settings are optimized for the below environment, adjust accordingly.

  • Software: Ubuntu 22.04/Debian 12+, Matlab 2022b+ & CUDA Toolkit 11.8+
  • Hardware: AMD Epyc Milan 24c/48t, Nvidia RTX3090 24gb & DDR4 ECC RAM 256gb.

Linux users: I highly recommend kernel 6.0 or higher, which contains numerous multi-core optimizations that noticeably improve electroCUDA runtime (validated for AMD Ryzen/Epyc, likely true for Intel 11th gen+ CPUs)

Dependencies

All dependencies are free & open-source except for Matlab & CUDA. I hope to go fully open-source by switching to Julia as it matures. Python & R are currently out of the question: can't compete with the FLOPS of Matlab or Julia.

Integrated dependencies

These dependencies have been modified & integrated into the main source code ~/src

  • ImaGIN – iEEG bad channel classifier. You must train on your machine, see ~/lib/ec_ImaGIN
  • CUDAICA – Infomax ICA with GPU acceleration (20x faster than CPU). You should recompile on your machine for hardware optimizations. Precompiled binaries are included as a last resort
  • AMICA – robust & nonstationary ICA with adaptive mixtures, better than Infomax but slow (CPU only, working on CUDA implementation)
  • NoiseTools – EEG preprocessing tools
  • Zapline Plus – adaptive electrical powerline denoising (i.e. 50hz/60hz AC current)
  • Artifact Subspace Reconstruction (ASR) – adaptive nonstationary denoising of field potential recordings
  • iELVis – anatomical preprocessing for intracranial electrodes
  • Image Similarity Toolbox – Analyze visual similarity of stimuli images
  • VLfeat – Computer vision algorithms (CUDA & CPU)
  • MatConvNet – Deep convolutional neural networks (CUDA & CPU)

Included dependencies

If you prefer an existing install, remove included dependency from the Matlab path ~/lib and set paths for existing install

  • Manopt – Optimization toolbox for matrices & manifolds
  • cbrewer2 - Colorbrewer 2: color palates optimized for scientific visualization (colorblind-friendly)
  • NeuralAct – required for projecting intracranial activity directly onto cortical surfaces

Excluded dependencies

These have to be installed yourself & are not included in this repository.

  • MATLAB – required for everything, sorry! Ideally use Matlab 2022b+, must use 2020a+ due to threaded parallelization & table functionality.
    • Statistics & Machine Learning Toolbox
    • Signal Processing Toolbox
    • Wavelet Toolbox
    • Parallel Computing Toolbox
  • CUDA – required for GPU acceleration (you need a Nvidia CUDA GPU!)
  • Freesurfer – required for anatomical preprocessing
  • EEGLAB – required for ASR & import/export between electroCUDA & EEGLAB formats
  • GRAMM – required for some statistical data visualization

Filestructure

Set directories

Set directories in ~/user/AddPaths.m

  • dirCode – base directory where you placed electroCUDA code (e.g. ~/electroCUDA)
  • dirMain – base directory for subject data
  • dirFreesurfer – Freesurfer subject directory
  • path_cudaica – full path to CUDAICA executable binary (compiled)

Code

Contents of ~/dirCode:

  • /bin – compiled executable binaries
  • /lib – included dependencies & libraries
  • /src – main source code
  • /user – options & specifications per project (each user must edit, move away from Git folder to avoid overwriting during updates)

Subject data

Files within ~/dirMain/subjectID/task:

  • x[suffix]_s[ID]_[task].mat – "x" matrices contain continuous timecourses for each channel or independent component. Field potential & single-band data is 2D while multi-frequency spectral data is 3D:
    • Indexing: x(frame,channel) x(frame,component) x(frame,channel,frequency) x(frame,component,frequency)
  • n[suffix]_s[ID]_[task].mat – "n" structs contain metadata for corresponding "x" matrices
  • chNfo_s[ID].mat – "chNfo" tables contain metadata per channel. chNfo.bad is a nested table of bad channel metrics. NOTE: independent component metadata stored in n.icNfo
  • psy_s[ID]_[task].mat - "psy" tables contain psychophysics data (trial type, stimuli, RT, etc) aligned to each frame of "x". Note: resampling from original sampling rate also resamples "psy", saved separately with sampling rate appended to filename e.g. psy100_s22_stroop.mat
  • taskNfo_s[ID]_[task].mat – "taskNfo" tables contain metadata per trial

Note: Anatomical data is kept in Freesurfer's directory structure

Suffixes

Suffixes indicate data type (channels or independent components) & frequency band. Multiple suffixes kept in order of processing steps. Suffixes and frequencies are user-editable.

  • no suffix – channel timecourses without ICA denoising or time-frequency decomposition (full-spectrum field potentials)
  • c – channel timecourses denoised by ICA (channel data subtracted by 'noisy' ICs)
  • i – independent component (IC) timecourses
  • s – multiple spectral frequencies (3D matrix, see indexing above)
  • d – delta band (1-4hz mean)
  • t – theta band (4-8hz mean)
  • a – alpha band (8-12hz mean)
  • b – beta band (12-30hz mean)
  • g – gamma band (30-60hz mean)
  • h – high-frequency broadband (60-200hz mean)

For example, denoised channel-space theta activity for subject 22's stroop task would be: xct_s22_stroop.mat. Spectral multi-frequency IC activity would be: xis_s22_stroop.mat. Corresponding metadata files start with "n" in place of "x" with otherwise the same filename.

Clone this wiki locally