eeg-connectivity

Framework for computing connectivity measures using EEG data

Description

Provides a general framework for computing connectivity analysis on EEG data.
Preprocess the data before useage; ICA, filtering or resampling the data, etc. is not part of the analysis pipeline.
The current pipeline was developed to work with EEGLAB data (.set, .fdt) files. Other file formats currently are not supported. The subject numbers are identified from the EEGLAB file name; the naming convention should be "{subject_number}*.fdt", "{subject_number}*.set" where subject_number uniquely identifies a subject.

Data I/O operations, connectivity calculation and visualizations are based on MNE. For more information about connectivity methods refer to the documentation here. Other useful tutorials about EEG data processing with MNE can be found here.

Setup

Clone and install requirements

$ git clone git@github.com:weiglszonja/eeg-connectivity.git
$ pip install -r requirements.txt

Create epochs

EEGLAB data (.set, .fdt) files are read from source_path variable which defaults to ./data/. Epochs are written to the location specified by target_path variable and defaults to ./epochs_{condition}/ where condition is the condition of the data (e.g. can be 'task' for data recorded during task, or 'resting' for data recorded during resting period). Condition name is also used when an EEG file was recorded in two or more pieces and the epochs are needed to be merged into one file.

The duration of epochs are set with EPOCH_LENGTH_IN_SECONDS top level variable and it defaults to 2.0 and is defined in seconds. For spectral connectivity measures it is recommended to use epochs that are overlapping at some amount of data points; this is defined with EPOCH_OVERLAP_RATIO top level variable and defaults to 0.5 that corresponds to 50% overlap between the generated epochs.

Running create_epochs_from_eeglab.py creates .fif files at target location containing the epochs created from EEGLAB data. It also generates a .csv file containing the number of epochs for each data file.

Execute the script by running the following command:

$ python utils/create_epochs_from_eeglab.py

Compute the power spectral density of epochs

The script compute_psd_from_epochs.py computes the power spectral density (PSD) of epochs generated from raw dataset.
Epochs (.fif) files are read from source_path variable. The condition variable can be defined as before to separate data by condition (e.g. resting data). The created figures are saved to the location defined by target_path.

There are two spectral estimation methods that can be used when computing the PSD: Welch and multitaper methods from MNE. The valid name of methods are ['welch', 'multitaper'] and is defined by a top level variable METHOD. The default estimation method is the Welch method.

The min frequency of interest is defined by F_MIN top level variable and defaults to 1.0 and is defined in Hz. The max frequency of interest is defined by F_MAX that defaults to 45.0 and is defined in Hz.

Running this script will create figures for each file in sub-directories under target location. The default path will save figures at ".result/{condition}/psd/plots". It will also create a multidimensional array containing the calculated spectral densities averaged over the epochs for each subject. The default location to save the file (.npy) is at ".result/{condition}/psd/".

Execute the script by running the following command:

$ python utils/compute_psd_from_epochs.py

Compute spectral connectivity between channels

Run connectivity analysis with -h argument to display help message
for list of keyword arguments and possible values:

$ python compute_channel_connectivity_from_epochs.py -h

usage: compute_channel_connectivity_from_epochs.py [-h]
                                                   [--condition CONDITION]
                                                   [--method METHOD]
                                                   [--workers WORKERS]

optional arguments:
  -h, --help            show this help message and exit
  --condition CONDITION, -condition CONDITION
                        The name of the condition (default="asrt")
  --method METHOD, -method METHOD
                        The name of the connectivity estimation method
                        (default=wPLI)
  --workers WORKERS, -w WORKERS
                        The number of epochs to process in parallel
                        (default=8)

Where method is the name of connectivity measure to compute, for supported values visit MNE documentation. Some of the supported connectivity measures are: pli, wpli, plv, coh ...
Specifying condition helps to separate the data (e.g. resting data, task data). Results are created at ./result/ where the sub-folders are structured as the following:
./result/{condition}/{method}. For each connectivity estimation method folders are created under ./result/{condition}/ with the name of the condition. E.g. ./result/asrt/wpli the results of wPLI connectivity that were computed from asrt epochs, and similarly at ./result/asrt/plv are the results of PLV connectivity.

Average channel connectivity into Regions of Interest (ROI)

Compute ROI averaging on channel connectivity data with -h argument to display help message for list of keyword arguments and possible values:

$ python compute_roi_from_channel_connecitivity.py -h

usage: compute_roi_from_channel_connecitivity.py [-h] [--condition CONDITION]
                                                 [--method METHOD]
                                                 [--verbose VERBOSE]

optional arguments:
  -h, --help            show this help message and exit
  --condition CONDITION, -condition CONDITION
                        The name of the condition (default="asrt")
  --method METHOD, -method METHOD
                        The name of the connectivity estimation method
                        (default=wPLI)
  --verbose VERBOSE, -verbose VERBOSE
                        Turn on interim processing: write to files (CSV)and
                        save heatmap figures (PNG) (default=False)

Specifying condition and method helps to locate the connectivity file (.npy). Averages channels into ROIs based on ./utils/settings.py where the ROI definitions are defined with the ROI variable. Example of channel definitions for 64 channels defined in ./utils/settings.py:

ROI = {'frontal_left': ['F7', 'F5', 'F3', 'FC5', 'FC3'],
       'frontal_central': ['F1', 'Fz', 'F2', 'FC1', 'FCz', 'FC2'],
       'frontal_right': ['F4', 'F6', 'F8', 'FC4', 'FC6'],
       'temporal_left': ['FT7', 'T7', 'TP7'],
       'central': ['C3', 'Cz', 'C4'],
       'temporal_right': ['FT8', 'T8', 'TP8'],
       'parietal_left': ['CP5', 'CP3', 'P7', 'P5', 'P3'],
       'parietal_central': ['CP1', 'CPz', 'CP2', 'P1', 'Pz', 'P2'],
       'parietal_right': ['CP4', 'CP6', 'P4', 'P6', 'P8'],
       'occipital_left': ['PO3', 'PO7', 'O1'],
       'occipital_right': ['PO4', 'PO8', 'O2']}