RESTINGLAB

RESTINGLAB is an open-source EEGLAB-based standalone software for automated/semi-automated Resting-State EEG data pre-processing and analyses.

Currently the software is in beta version which means it may still contains errors.
Contributions are thus more than welcome.

⚠️ OF NOTE: This software can currently only import BioSemi 64-channels EEG files.

Throughout the Guided User Interfaces (GUIs) you will find additional information while pressing on the ❓ buttons.

Getting Started
Dependencies
Authors
License
Acknowledgements
Fundings

Table of contents generated with markdown-toc

Getting Started

When on the RESTINGLAB startup page, start by clicking on ⬇️ Code on the top right of the screen and then Download ZIP to download the whole repository (alternatively you can also clone it).

To run the GUI, double click the MainGUI.mlapp file that you will find in the repository.

The main page of the GUI will open up:

At this stage, all the buttons are RED 🔘, meaning that no parameters have been yet defined and the script cannot run.

Hence, first, you should decide whether:

* You want to run the Preprocessing phase only, the Analysis phase only or both of them (bottom switch)
* You want to define new parameters or want to load existing ones (LOAD PARAMETERS button)

Then, you should proceed sequentially by following the sequence of buttons (see below for detailed explanations):

1.Design ➡️ 2.Parameters ➡️ 3.Preprocessing ➡️ 4.Analyses ➡️ START

1.Design

Start by defining your experimental design, i.e. within- and/or between-subjects factor(s) and respective levels in the corresponding fields.
The software can accomodate up to 1 within- and 1 between-subjects factors each including 3 levels.
Be careful as NO SPACES are allowed in the names.

Within-subject factor (WS) The names chosen for each WS factor level should perfectly match the common names of your files.
For example, if your files contain the patterns "_awake.bdf" & "_asleep.bdf", you should define the levels correspondingly: "awake" & "asleep".

Between-subject factor (BS) Similarly, for the BS factor you should name each level respectively to the folders in which you stored their files.
For example, if you stored your EEG data separately in two folders Experimental & Placebo, you should define the levels correspondingly: "Experimental" & "Placebo".

Once you are satisfied with your design, press the DIRECTORY button.
A number of windows will pop-up in order for you to define the path of each BS factor level's folder.
!Have a look at the title of each pop-up window to know which level you need to indicate a path for!

Once done, you will see a last pop-up window asking you where you want to save all the files that will be exported.

1.1.Participants Assignment

Then, press the ALLOCATION button to start defining which file belongs to what WS and/or BS levels.
In the top field you have the possibility to define the subjects' number that you want to include (each number should be separated by a space).
DO NOT leave any empty line in the table as the software may crash.

You can also load existing parameters (LOAD PARAMETERS button, i.e. look for the Conditions_order.xlsx file).

When you are happy with your choice, press SAVE.
By doing so, the Conditions_order.xlsx file will generate in the folder your exports folder.

1.2.Subjects

Now, you can press the SUBJECTS button which will allow you to select files to include and/or exclude.\ Since this GUI is redundant with the previous the ALLOCATION GUI, it might be deleted in future releases.
Again, press the SAVE button when you are satisfied with your selection.

Finally, you can press the SAVE button when you are back to the Design GUI to switch to the next section.

2.Parameters

In the second GUI you have to define a few EEG data related parameters such as the extension (currently restricted to .bdf), sampling rate, channels, etc.
Importantly, in the top left field you should indicate a name that is common to all your files (e.g. "Subj").
This is important especially to avoid loading unrelated .bdf files that might be stored in your subfolders.
You can try to leave the field empty, but the software may crash

Press the press the SAVE button to switch to the next section.

3.Preprocessing

The third GUI provides the user with the possibility to activate/deactivate specific algorithms (e.g. sleep detection (currently not working), ICA, ASR, etc.)
Once you activate one of the algorithm (i.e. switch to YES), you can access their respective Optional Parametersbelow which are already filled with defaults.
On the right side, you can activate the computation of Global Power Spectra and define which frequencies would you like to generate topographical plots (i.e. topoplots) for each file.
If the GPS swich is on, you will be able to define the frequency bands of interest in the table below. Use the ADD LINE and REMOVE LINE button to adjust the table.

Finally, you can also define clusters of electrodes to compute the GPS (i.e. 2. GPS on Scalp Areas), which will generate the following pop-up window:
The first line enables to define the name of each cluster (separated by a space), while in each line you need to indicate the number or name of channels included in each cluster.

3.1.AreasList

Press the press the SAVE button to switch to the next section.

4.Analyses

This last GUI enables you to run group and/or condition-wise statistical analyses.
This part is still under construction hence only few features are currently available.

You have the possibility to redefine at this stage which files should be included in the analysis part by switching the Subjects switch to Subset.
This will generate another GUI enabling you to include/exclude the files.

On the right side, you can define whether to perform:

1.Frequency bands-level analyses (default is YES)
2. MicroStates analyses (default is NO)
3.Independent Components (IC) clustering and source localization (default is NO)

⚠️ OF NOTE, the MicroStates analysis is running but needs additionnal testing and the IC clustering analysis is currently NOT WORKING.

Both the MicroStates and the IC Clustering analyses have respective setting that can be accessed by clicking on the Settings button.

Press the press the SAVE button to go back to the main GUI.

As soon as all the buttons have turned to GREEN 🔘, you can run the script by clicking on the START button.

Exports

The structure of the exportation folders will always be the same independent of your selection (i.e. some folders might remain empty):

📁 [Save Folder]
 ↳ 📁 [Group] 
    ↳ 🧠 design1_X_Group.datspec
    ↳ 🧠 FolderName_Condition_ExportSelection.fdt
    ↳ 🧠 FolderName_Condition_ExportSelection.set
    ↳ 🧠 FolderName_Condition_Preprocessed.bdf
 ↳ 📋 RESTINGLablog_DD_MM_YYYY-HH_MM.txt
 ↳ 📁 [Excel]
    ↳ 📁 [DD_MM_YYYY-HH_MM]
       ↳ 📋 Conditions_order.xlsx
       ↳ 📋 AreaAmplitudeFrequency.xlsx
       ↳ 📋 AsleepAwakeTrials.xlsx
       ↳ 📋 GPS_Frequency.xlsx
       ↳ 📋 InterpChannelsCondition.xlsx
       ↳ 📋 RejectedComponentsCondition.xlsx
 ↳ 📁 [Exports]
    ↳ 📁 [DD_MM_YYYY-HH_MM]
       ↳ 📁 [ICClust]
          ↳ 👷 UNDER CONSTRUCTION...
          ↳ 📁 [DomainX]
             ↳ 📊 SourceClustX_STUDY.bmp
             ↳ 📊 SourceClustX_STUDY.fig
             ↳ 📋 ICClustOutput_Domain4.txt
             ↳ 👷 UNDER CONSTRUCTION...
       ↳ 📁 [MicroStatesSegment]
          ↳ 📁 [VersionX]
             ↳ 📊 GFP_SX_condition_vX.bmp
             ↳ 💾 MicroStateRes_SX_condition_vX.mat
             ↳ 📁 [Fig]
                ↳ 📊 GFP_SX_condition_vX.fig
       ↳ 📁 [SleepNoSleep]
          ↳ 👷 UNDER CONSTRUCTION...
          ↳ 📊 WaveletMorletSleep_X_condition.bmp
       ↳ 📁 [SourceLocalisation]
          ↳ 📁 [Frequency]
             ↳ 💾 SX_Frequency_Group.ep
       ↳ 📁 [Topoplots]
          ↳ 📊 PowerSpectrumX_Group.bmp
       ↳ 📁 [TopoplotsDipFit]
          ↳ 📊 DipFitX_Group.bmp
          ↳ 📁 [LabelDipoles]
             ↳ 📊 LabelsFitX_Group.bmp
             ↳ 📊 LabelsFitBarX_Group.bmp
 ↳ 📁 [Parameters]
    ↳ 📁 [DD_MM_YYYY-HH_MM]
       ↳ 💾 AnalysesGUI.mat
       ↳ 💾 EEGParamGUI.mat
       ↳ 💾 GUIDesign.mat
       ↳ 💾 GUIPartList.mat
       ↳ 💾 GUIPreProcessing.mat
       ↳ 💾 GUISubjects.mat
       ↳ 💾 StudyGUI.mat
 ↳ 📁 [STUDY]
    ↳ 📁 [DD_MM_YYYY-HH_MM]
       ↳ 💾 SpectralData.mat
       ↳ 🧠 STUDY.study
       ↳ 🧠 STUDY_Clustered.study
       ↳ 📊 Boxplot_Frequency_STUDY_1.bmp
       ↳ 📊 ChanAVG_Group_STUDY.bmp
       ↳ 📊 Topoplots_STUDY_Frequency.bmp
       ↳ 📊 WholeSpect_STUDY.bmp
       ↳ 📁 [MicroStates]
          ↳ 📊 ClusterTopo_Group_STUDY_vX.bmp
          ↳ 📊 FitMeasures_OH_STUDY_vX.bmp
         
------------------------------------------------------------------         
Group            = Names of the levels of the BS factor
condition        = Names of the levels of the WS factor
FolderName       = Name of the subject folder
ExportSelection  = Name of the .set files you decided to save (see 2.Parameters)
Frequency        = Names that you gave to the frequency bands of interest
X                = Subject number X
vX / VersionX    = Version of analysis number X
SourceClustX     = Cluster of significant results number X
DomainX          = Brain spatial domain number X
DD_MM_YYYY-HH_MM = Date and time of analysis
📁 [Group]       = This folder will reproduce the structure of your 
                    data folders and will include the desired .set files 
------------------------------------------------------------------

FILES	Content
RESTINGLablog_DD_MM_YYYY-HH_MM.txt	Log generated for each run of the script containing a complete summary of all selected parameters and included files
Conditions_order.xlsx	List of subjects and condition/group assignment (WS and/or BS factors levels)
AreaAmplitudeFrequency.xlsx	List of subjects and associated maximum/minimum GPS values and cluster (optional, see `AreasList`)
AsleepAwakeTrials.xlsx	List of subjects and associated number of Xseconds (user-defined in GUI) asleep and awake epochs
GPS_Frequency.xlsx	List of subjects and GPS values for each EEG channel (columns). There is one excel file for each frequency band of interest and inside each file there is one sheet for each WS factor level.
InterpChannelsCondition.xlsx	List of subjects and related channels label(number) that were automatically interpolated
RejectedComponentsCondition.xlsx	List of subjects and related independent components (ICs) that were semi-automatically rejected
ICClustOutput_Domain4.txt	Text file informing about anatomical information and voxels inside one cluster showing significant group and/or condition differences
MicroStateRes_SX_condition_vX.mat	Data matrix containing all the outputs generated from the main MST functions
SX_Frequency_Group.ep	1x64 matrix containing the time-averaged GPS for each of the 64 channels, for each frequency band of interest and condition. The .ep format can be opened in STEN and CARTOOL, resp. to perform statistics and apply inverse source solutions
AnalysesGUI.mat	Data matrix generated by the Preprocessing GUI
EEGParamGUI.mat	Data matrix generated by the Parameters GUI
GUIDesign.mat	Data matrix generated by the Design GUI
GUIPartList.mat	Data matrix generated by the Design GUI
GUIPreProcessing.mat	Data matrix generated by the Preprocessing GUI
GUISubjects.mat	Data matrix generated by the Design GUI
StudyGUI.mat	Data matrix generated by the Analyses GUI
SpectralData.mat	Data matrix containing the power spectra data following EEGLAB format, namely lines = WS levels & columns = BS levels. Inside each cell, the spectral data is formatted as follows: frequency bins X channels X subjects
STUDY.study	EEGLAB STUDY structure for the group and/or condition-levels analyses
STUDY_Clustered.study	EEGLAB STUDY structure for the IC clustering analysis
design1_X_Group.datspec	Spectrum data for data channels
FolderName_Condition_ExportSelection.fdt	Float data containing raw data
FolderName_Condition_ExportSelection.set	Meta-information (number of channels, sampling frequency etc...)
FolderName_Condition_Preprocessed.bdf	BioSemi EEG file generated after preprocessing and which can be easily open in CARTOOL

Dependencies

PLUGINS	Description
EEGLAB v2020.0	Main software that manages most of the preprocessing and analyses toolboxes described in the table below
FMUT v0.5.1	Computation of permutation-based statistics
ept_TFCE	Computation of permutation-based statistics and TFCE correction
Automatic Human Sleep Stage Scoring Using Deep Neural Networks	Algorithm to classify sleep stages
LBPA40 atlas v2011-04-28	The LONI LBPA40 atlas is a high-quality probabilistic atlas
CubeHelix v2.0	Color scheme generator
mColonFolder v1.6.0	Enables concatenation of multiple colon-intervals
Gramm	Gramm is a powerful plotting toolbox which allows to quickly create complex, publication-quality figures in Matlab, and is inspired by R's ggplot2 library
PrepPipeline v0.55.3	The PREP pipeline is a standardized early-stage EEG processing pipeline that focuses on the identification of bad channels and the calculation of a robust average reference

EEGLAB EXTENSIONS	Description
AMICA v1.5	The Adaptive Mixture Independent Component Analysis (AMICA) toolbox provides the best IC decomposition
MPT v1.661	Probabilistic approach to EEG source comparison and multi-subject inference
BLINKER v1.1.2	BLINKER is an automated pipeline for detecting eye blinks in EEG and calculating various properties of these blinks
ASR v2.0	ASR (automated subspace removal) detects and rejects or removes high-amplitude non-brain ('artifact') activity (produced by eye blinks, muscle activity, sensor motion, etc.) by comparing its structure to that of known artifact-free reference data
CleanLine v1.04	This plugin adaptively estimates and removes sinusoidal (e.g. line) noise from your ICA components or scalp channels using multi-tapering and a Thompson F-statistic
EEGBrowser v1.0	Enhanced visualization for continuous EEG recordings
fitTwoDipoles v0.01	Routine for automated recommendation of ICs that may be best fit with a position-symmetric dual-dipole model
ICLabel v1.2.4	Automatic independent component (IC) classifcation based on the ICLabel project's classifier
MST v1.0	Tee toolbox includes ability to run microstate analysis on both ERP and spontaneous (e.g. resting state) EEG
Viewprops v1.5.4	Enhanced visualization of independent components (ICA)

Isolated functions:

The dependencies are already included in the Dependencies folder.

Authors

Corentin Wicht
SNSF Doc.CH PhD student
[email protected], [email protected]
Laboratory for Neurorehabilitation Science
University of Fribourg, Switzerland

Christian Mancini
Research assistant
[email protected]
Laboratory for Cognitive and Neurological Sciences
University of Fribourg, Switzerland

License

This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

See the LICENSE.md file for details

Acknowledgements

Dr. med. Joelle Chabwine, PD Dr. Lucas Spierer and Prof. Jean-Marie Annoni from the University of Fribourg and the Fribourg County Hospital provided substantial support and advices regarding theoretical conceptualization as well as access to the workplace and the infrastructure required to successfully complete the project. Additionally, Hugo Najberg and Dr. Michael Mouthon provided valuable advices regarding programming issues in MATLAB and technical support.

Fundings

This project was supported by Swiss National Science Foundation grants:

#P0LAP1_181689 to Corentin Wicht
#320030_175469 to PD Dr. Lucas Spierer
JOELLE + JMA ???

hugonjb / restinglab Goto Github PK

restinglab's Introduction