Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@arnodelorme
arnodelorme authored Apr 3, 2024
1 parent e80177f commit 81336dd
Showing 1 changed file with 26 additions and 15 deletions.
41 changes: 26 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,14 @@ ROIconnect is a freely available open-source plugin to [EEGLAB](https://github.c
You can choose to access the core functions from the EEGLAB GUI. Experienced users can access additional utilities from the command line. If you do decide to run a function from the command line, please refer to the respective documentation provided in the code.


Code developed by Tien Dung Nguyen, Franziska Pellegrini, and Stefan Haufe, with EEGLAB interface, coregistration, 3-D vizualisation and Fieldtrip integration performed by Arnaud Delorme.
Code developed by Tien Dung Nguyen, Franziska Pellegrini, and Stefan Haufe, with EEGLAB interface, coregistration, 3-D visualization, and Fieldtrip integration performed by Arnaud Delorme.

# Installation
First of all, please make sure to have [EEGLAB](https://github.com/sccn/eeglab#installingcloning) installed. Your project layout should look as follows
# Installation using EEGLAB plugin manager

First, install EEGLAB. Then, use menu item *File > Manage EEGLAB extensions*, select *ROIconnect*, and install. ROIconnect menu items are located in the *Tools* EEGLAB menu.

# Manual installation
First, please make sure to have [EEGLAB](https://github.com/sccn/eeglab#installingcloning) installed. Your project layout should look as follows.

```
eeglab/
Expand All @@ -28,11 +32,11 @@ eeglab/
├── tutorial_scripts/
└── /.../
```
The ROIconnect plugin should be installed in the `plugins` folder. The easiest way to do so is to simply clone our repository. Navigate to the `plugins` folder by typing
The ROIconnect plugin should be installed in the `plugins` folder. The easiest way to do so is to simply clone our repository. Navigate to the `plugins` folder by typing.
```
cd <eeglab_install_location>/eeglab/plugins
```
Next, clone the repository
Next, clone the repository.
```
git clone https://github.com/sccn/roiconnect.git
```
Expand All @@ -43,23 +47,26 @@ Why is this EEGLAB plugin not in the EEGLAB plugin manager? The plugin is beta.
📌 `test_pipes/` includes some test pipelines which can be used to get started.

# Key features
The features of the toolbox are implemented in the following three main functions: `pop_roi_activity`, `pop_roi_connect` and `pop_roi_connectplot`.
The features of the toolbox are implemented in the following three main functions: `pop_roi_activity`, `pop_roi_connect` and `pop_roi_connectplot`. These functions have corresponding menus (documentation coming soon). For now, only the command line version of these functions is documented below.

## Data Preparation
You will need a leadfield matrix with an associated atlas to use ROIconnect. A leadfield matrix may be computed using the DIPFIT EEGLAB plugin (menu item *Tools > Source localization using DIPFIT > Head model settings* then *Tools > Source localization using DIPFIT > Distributed source leadfield matrix*). This leadfield matrix will be automatically recognized by ROIconnect.

## Source reconstruction
## Source Reconstruction
`pop_roi_activity` asks for the following inputs: an EEG struct containing EEG sensor activitiy, a pointer to the headmodel and a source model, the atlas name and the number of PCs for the dimensionality reduction. In addition, this function also supports [FOOOF analysis](https://fooof-tools.github.io/fooof/). Here is a command line example including FOOOF:

```matlab
EEG = pop_roi_activity(EEG, 'leadfield',EEG.dipfit.sourcemodel,'model','LCMV','modelparams',{0.05},'atlas','LORETA-Talairach-BAs','nPCA',3, 'fooof', 'on', 'fooof_frange', [1 30]);
```

The function performs source reconstruction by calculating a source projection filter and applying it to the sensor data. Power is calculated with the Welch method on the voxel time series and then summed across voxels within regions. To enable region-wise FC computation, the function applies PCA to the time series of every region. It then selects the *n* strongest PCs for every region. The resulting time series is stored in `EEG.roi.source_roi_data`, and power is stored in `EEG.roi.source_roi_power`.
The function performs source reconstruction by calculating a source projection filter and applying it to the sensor data. Power is calculated using the Welch method on the voxel time series and then summed across voxels within regions. To enable region-wise FC computation, the function applies PCA to the time series of every region. It then selects the *n* strongest PCs for every region. The resulting time series is stored in `EEG.roi.source_roi_data`, and power is stored in `EEG.roi.source_roi_power`.

Note that the function require the data to be about 100 Hz, so it queries the user for resampling data. It also extract data segment of 2 seconds I have change the automatic epoch (segment) extraction for continuous data and also added a parameter for the number of epochs. Connectivity values vary with the length of the data so we always want to have the same number of epochs.
Note that the function requires the data to be about 100 Hz, so it queries the user for resampling data. It also extracts data segment of 2 seconds I have changed the automatic epoch (segment) extraction for continuous data and also added a parameter for the number of epochs. Connectivity values vary with the length of the data so we always want to have the same number of epochs.

Say we set the number of epochs to 60 (2 second epochs). When you provide continuous data, then non-overlapping epochs are extracted. If there are more than 60, then the function selects 60 randomly. If there are less than 60, then the function increases the epoch overlap and try to extract data epochs again. If you provide data epochs as input (single trial ERPs), and there are not enough of them, they are bootstraped to reach the desired number.

## Connectivity analysis
`pop_roi_connect` accepts the following inputs: the EEG struct computed by `pop_roi_activity` and the names of the FC metrics. To avoid biases due to data length, we recommend keeping data length for all conditions constant. Thus, you can tell the function to estimate FC on time snippets of 60 s length (default) which can be averaged (default) or used as input for later statistical analyses. The following command line example asks the function to perform FC analysis on snippets using default values (explicitely passed as input parameters in this example).
`pop_roi_connect` accepts the following inputs: the EEG struct computed by `pop_roi_activity` and the names of the FC metrics. To avoid biases due to data length, we recommend keeping data length for all conditions constant. Thus, you can tell the function to estimate FC on time snippets of 60 s length (default) which can be averaged (default) or used as input for later statistical analyses. The following command line example asks the function to perform FC analysis on snippets using default values (explicitly passed as input parameters in this example).

```matlab
EEG = pop_roi_connect(EEG, 'methods', { 'MIM', 'TRGC'}, 'snippet', 'on', 'snip_length', 60, 'fcsave_format', 'mean_snips');
Expand All @@ -71,13 +78,13 @@ The function computes all FC metrics in a frequency-resolved way, i.e., the outp
> Snippet analysis IS NOT equivalent to epoching. We discovered that the data length imposes a bias on the connectivity estimate. We therefore recommend keeping the data length (i.e. snippet length, default 60 s) constant across all experimental conditions that should be compared. This is most relevant for iCOH and MIM/MIC. By default, the snippet analysis is turned off (default: `'snippet', 'off'`). For more details, click [here](https://github.com/arnodelorme/roiconnect/pull/14#issuecomment-1263531505).
## Visualization
You can visualize power and FC in different modes by calling `pop_roi_connectplot`. Below, we show results of a single subject from the real data example in [[1]](#1). You can find the MATLAB code and corresponding analyses [here](https://github.com/fpellegrini/MotorImag). The plots show power or FC in left motor imagery condition. Due to the nature of the task, we show results in the 8 to 13 Hz frequency band but you are free to choose any frequency or frequency band you want.
You can visualize power and FC in different modes by calling `pop_roi_connectplot`. Below, we show the results of a single subject from the real data example in [[1]](#1). You can find the MATLAB code and corresponding analyses [here](https://github.com/fpellegrini/MotorImag). The plots show power or FC in the left motor imagery condition. Due to the nature of the task, we show results in the 8 to 13 Hz frequency band but you are free to choose any frequency or frequency band you want.

:pushpin: If any of the images are too small for you, simply click on them, they will open in full size in another tab.<br>
:round_pushpin: Plotting is particularly optimized for PSD, MIM/MIC and GC/TRGC.
:pushpin: If any of the images are too small for you, simply click on them, and they will open in full size in another tab.<br>
:round_pushpin: Plotting is particularly optimized for PSD, MIM/MIC, and GC/TRGC.

### Power as a region-wise bar plot
If you wish to visualize power as a barplot only, please make sure to explicitely turn `plotcortex` off because it is turned on by default.
If you wish to visualize power as a barplot only, please make sure to explicitly turn `plotcortex` off because it is turned on by default.
```matlab
EEG = pop_roi_connectplot(EEG, 'measure', 'roipsd', 'plotcortex', 'off', 'plotbarplot', 'on', 'freqrange', [8 13]) % alpha band;
```
Expand All @@ -96,7 +103,7 @@ EEG = pop_roi_connectplot(EEG, 'measure', 'roipsd', 'plotcortex', 'on', 'freqran
</p>

### FC as region-to-region matrix
Again, if you do not wish to see the cortex plot, you should explicitely turn `plotcortex` off. Please click on the figure if you want to see it in full size.
Again, if you do not wish to see the cortex plot, you should explicitly turn `plotcortex` off. Please click on the figure if you want to see it in full size.
```matlab
EEG = pop_roi_connectplot(EEG, 'measure', 'mim', 'plotcortex', 'off', 'plotmatrix', 'on', 'freqrange', [8 13]);
```
Expand Down Expand Up @@ -179,6 +186,10 @@ Alternatively, to get ROIconnect data from an arbitrary study design (including

Then, proceed to use the compute statistics and plot as above (in this case *condsMat = { cond1 cond2 }*). For more information on how to create a STUDY and STUDY design, refer to the [EEGLAB documentation](https://eeglab.org/tutorials/10_Group_analysis/study_creation.html).

# Script

The test folder of ROIconnect contains a variety of scripts. Of interest is the *test_pipes/pipeline_connectivity.m* which runs connectivity analysis on the EEGLAB tutorial dataset. This script can easily be modified to process other data.

# References
<a id="1">[1]</a>
Pellegrini, F., Delorme, A., Nikulin, V., & Haufe, S. (2023). Identifying good practices for detecting inter-regional linear functional connectivity from EEG. NeuroImage, 120218. [doi: 10.1016/j.neuroimage.2023.120218](https://doi.org/10.1016/j.neuroimage.2023.120218)
Expand Down

0 comments on commit 81336dd

Please sign in to comment.