Skip to content

This toolbox enables to automatically preprocess and analyze resting-state Biosemi EEG files, relying on the EEGLAB software and additional toolboxes.

License

Notifications You must be signed in to change notification settings

CorentinWicht/RESTINGLAB

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

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.

Cite the repository

C.A. Wicht, RESTINGLAB, (2020), GitHub repository, https://github.com/CorentinWicht/RESTINGLAB
DOI

Table of Contents

Table of contents generated with markdown-toc

Getting Started

Structuring your files and folders

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]
...
  1. 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
  2. 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!).
  3. File inside each Participant folders, should represent the Within-subject factor levels (e.g. Condition1.bdf).
  4. Optionally, you can create an OUTPUTS folder in which you can decide to save the outputs of the analyses.

Guided User Interfaces

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 be generated in 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

Preprocessing Pipeline

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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. \
  5. MST:
    [9] Poulsen, A.T., Pedroni, A., LAnger, N. & Hansen, L.K. (2012). Microstate EEGlab toolbox: An introductory guide. bioRxiv, 289850.
  6. 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.
  7. 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.
  8. ept_TFCE :
    [13] Mensen, A. & Khatami, R. (2013). Advanced EEG analysis using threshold-free cluster-enhancement and non-parametric statistics. NeuroImage, 67, 111-118.
  9. 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.

Dependencies

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:

The dependencies are already included in the Dependencies folder.

Authors

Corentin Aurèle 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

Creative Commons 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:

About

This toolbox enables to automatically preprocess and analyze resting-state Biosemi EEG files, relying on the EEGLAB software and additional toolboxes.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published