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.
Throughout the Guided User Interfaces (GUIs) you will find additional information while pressing on the ❓ buttons.
C.A. Wicht, RESTINGLAB, (2020), GitHub repository, https://github.com/CorentinWicht/RESTINGLAB
Table of contents generated with markdown-toc
The structure of your files and folder has to be done as following:
📁 [Group1]
↳ 📁 [Participant1]
↳ 🧠 Condition1.bdf
↳ 🧠 Condition2.bdf
↳ 📁 [Participant2]
↳ 🧠 Condition1.bdf
↳ 🧠 Condition2.bdf
📁 [Group2]
↳ 📁 [Participant6]
...
📁 [OUTPUTS]
...
- The first level of folders, e.g.
Group1, should be the Between-subject factor levels. If you don't have a between-subject factor, name it for e.g.Data - The second level of folders, e.g.
Participant1, should correspond to the participant number (i.e. important to have the number at the end of the folder name!). - File inside each
Participantfolders, should represent the Within-subject factor levels (e.g.Condition1.bdf). - Optionally, you can create an
OUTPUTSfolder in which you can decide to save the outputs of the analyses.
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
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.
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 be generated in your exports folder.
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.
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.
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.
Press the press the SAVE button to switch to the next section.
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)
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.
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 |
The pipeline structure was inspired from :
Makoto's preprocessing pipeline
[1]
Bidgely-Shamlo, N., Mullen, T., Kothe, C., Su, K.-M. & Robbins, K.A. (2015).
The PREP pipeline: standardized preprocessing for large-scale EEG analysis.
Frontiers in Neuroinformatics, 9, 1-20.
[2]
Gabard-Durnam, L.J., Mendez Leal, A.S., Wilkinson, C.L. & Levin, A.R. (2018).
The Harvard Automated Processing Pipeline for Electroencephalography (HAPPE): Standardized Processing Software for Developmental and High-Artifact Data.
Frontiers in Neuroscience, 12, 1-24.
The choice of the EEGLAB toolboxes included in the pipeline were made according to:
BLINKER:
[3] Kleifges, K., Bidgely-Shamlo, N., Kerick, S.E. & Robbins, K.A. (2017). BLINKER: Automated Extraction of Ocular Indices from EEG Enabling Large-Scale Analysis. Frontiers in Neuroscience, 11, 1-17.ASR:
[4] Chang, C.-Y. Hsu, S.-H., Pion-Tonachini, L. & Jung, T.-P. (2018). Evaluation of Artifact Subspace Reconstruction for Automatic EEG Artifact Removal. Conf Proc IEEE Eng Med Biol Soc, 1242-1245.
[5] Mullen, T.R., Kothe, C.A.E., Chi, Y.M., Ojeda, A., Kerth, T., Makeig, S., Jung, T.-P. & Cauwenberghs, G. (2015). Real-Time Neuroimaging and Cognitive Monitoring Using Wearable Dry EEG. IEEE Trans Biomed Eng, 62(11), 2553-2567.ICLABEL:
[6] Pion-Tonachini, L., Kreutz-Delgado, K. & Makeig, S. (2019). ICLabel: An automated electroencephalographic independent component classifier, dataset, and website. NeuroImage, 198, 181-197.AMICA:
[7] Delorme, A., Parlmer, J., Onton, J., Oostenveld, R. & Makeig, S. (2012). Independent EEG Sources Are Dipolar. PLoS ONE, 7(2), e30135.
[8] Parlmer, Makeig, S., Kreutz-Delgado, K. & Rao, B.D. (2008). Newton method for the ICA mixture model. 2008 IEEE International Conference on Acoustics, Speech and Signal Processing, Las Vegas, NV, 2008, pp. 1805-1808. \MST:
[9] Poulsen, A.T., Pedroni, A., LAnger, N. & Hansen, L.K. (2012). Microstate EEGlab toolbox: An introductory guide. bioRxiv, 289850.MPT:
[10] Balkan, O., Virji-Babul, N., Miyakoshi, M., Makeig, S. & Garudadri, H. (2015). Source-domain spectral EEG analysis of sports-related concussion via Measure Projection Analysis. Conf Proc IEEE Eng Med Biol Soc, 4053-4056.
[11] Bigdely-Shamlo, N., Mullen, T., Kreutz-Delgado, K. & Makeig, S. (2013). Measure projection analysis: a probabilistic approach to EEG source comparison and multi-subject inference. Neuroimage, 72, 287-303.Multiquadratic interpolation:
[12] Jäger, J., Klein, A., Buhmann, M. & Skrandies, W. (2016). Reconstruction of electroencephalographic data using radial basis functions. Clinical Neurophysiology, 127(4), 1978-1983.ept_TFCE:
[13] Mensen, A. & Khatami, R. (2013). Advanced EEG analysis using threshold-free cluster-enhancement and non-parametric statistics. NeuroImage, 67, 111-118.FMUT:
[14] Groppe, D.M., Urbach, T.P. & Kutas, M. (2011). Mass univariate analysis of event-related brain potentials/fields I: a critical tutorial review. Psychophysiology, 48(12), 1711-1725.
Additional recommended publications on the topic:
[15]
Chaumon, M., Bishop, D.V.M. & Busch, N.A. (2015).
A practical guide to the selection of independent components of the electroencephalogram for artifact correction.
J Neurosci Methods, 30, 47-63.
[16]
Jung, T.P., Makeig, S., Humphries, C., Lee, T.W., McKeown, M.J., Iragui, V. & Sejnowski, T.J. (2011).
EEGLAB, MPT, NetSIFT, NFT, BCILAB, and ERICA_New tools for Advanced EEG Processing.
Computational Intelligence and Neuroscience, e130714.
[17]
Jung, T.P., Makeig, S., Humphries, C., Lee, T.W., McKeown, M.J., Iragui, V. & Sejnowski, T.J. (2000).
Removing electroencephalographic artifacts by blind source separation.
Psychophysiology, 37(2), 163-178.
| PLUGINS | Description |
|---|---|
| EEGLAB v14.1.2b | Importing the .set EEG files |
| 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 | The 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:
- Timerwaitbar v1.02 (upgraded)
- bluewhitered v1.00
- limo_FDR from the LIMO Toolbox
- natsort v2.10
- saveeph
- textprogressbar v1.00
- topoplotIndie
- vis_artifacts
- hline v1.00 & vline v1.00
- Composite Colormap v1.00
- ShadedErrorBar v3.00
- getdrives v1.3.0.1
- RemoveSheet123 v1.0
- sort_nat v1.4
- xlsColNum2Str v1.4
The dependencies are already included in the Dependencies folder.
Corentin Aurèle Wicht
SNSF Doc.CH PhD student
corentin.wicht@unifr.ch, corentinw.lcns@gmail.com
Laboratory for Neurorehabilitation Science
University of Fribourg, Switzerland
Christian Mancini
Research assistant
christian.mancini@unifr.ch
Laboratory for Cognitive and Neurological Sciences
University of Fribourg, Switzerland
This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.
See the LICENSE.md file for details
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.
This project was supported by Swiss National Science Foundation grants:
- #P0LAP1_181689 to Corentin Wicht
- #320030_175469 to PD Dr. Lucas Spierer