Skip to content

Home

Jump to bottom
Corentin Wicht edited this page Jan 21, 2022 · 19 revisions

autoBIDS

Downloading the repository

When on the autoBIDS startup page, start by clicking on ⬇️ Code, then Download ZIP to download the whole repository.

This is how the folder structure looks like:

📁 [Functions]
 ↳ 📁 [eeglab2021.0]
 ↳ 📃 natsort.m
📁 [ChanLocs]
 ↳ ⚙️  biosemi64.locs
 ↳ ⚙️  biosemi128.xyz
📃 BIDS.m
📃 LICENSE.md
📃 README.md

Be sure to run MATLAB with administrator privileges to avoid errors related to BIDS metadata generation (see BIDS export error) and then open the BIDS.m script to start.

Table of Contents

Getting Started

Loading Raw EEG files

Firs, provide the most upper directory containing all your raw EEG files (i.e. the folder containing all other subfolders).

Loading marker files (optional)

Secondly, syou can load Biosemi-specific marker files (.mrk files) containing triggers information. This step is optional since triggers may already be embedded in each raw EEG file.

Loading channels location file

Then, provide the channels location file.
In the ChanLocs 📁 folder you will find channels location file for the BioSemi 64 and 128 electrodes caps.

Preprocessing parameters

In this prompt you need to specify:

  • How many electrodes were used for the recordings (all EEG files must have been recorded with the same number of electrodes!).
  • The number corresponding to the reference electrode (based on channels location file).
  • The name you would like to give to the study that will be stored in the MATLAB's current folder.
  • If you would like to add a delay to all triggers timings loaded from the .mrk files (optional).

BIDS design parameters

This is the most crucial and case-sensitive part of the script.

This prompt will enable to automatically create the EEGLAB study and autopopulate some of the BIDS information. \

It is divided into 4 categories for which the same principles of matching patterns apply:

  • SUBJECTS: the unique name of the subjects index in your files/folders structure
  • TASKS: the unique name of the task(s) in your files/folders structure (! mandatory to specify at least ONE task !)
  • FILES/RUN: The unique name of the runs if you have divided your task in multiple recordings, e.g. for each block of trials
  • SESSIONS: The unique name of the sessions between which the EEG cap has been removed

The concept is for each of the category to specify:

  • The unique identifier
  • Whether this identifier is found in files [1] or folders [2]

Let's take an example of a raw EEG data structure:

📁 [DATA]
 ↳ 📁 [GNG] 
    ↳ 🧠 Sub1_Ses1_B1.bdf
    ↳ 🧠 Sub1_Ses1_B2.bdf
    ↳ 🧠 Sub1_Ses2_B1.bdf
    ↳ 🧠 Sub1_Ses2_B2.bdf
    ↳ 🧠 Sub2_Ses1_B1.bdf
    ↳ 🧠 Sub2_Ses1_B2.bdf
    ↳ 🧠 Sub2_Ses2_B1.bdf
    ↳ 🧠 Sub2_Ses2_B2.bdf
 ↳ 📁 [NBACK]
    ↳ 🧠 Sub1_Ses1_B1.bdf
    ↳ 🧠 Sub1_Ses1_B2.bdf
    ↳ 🧠 Sub1_Ses2_B1.bdf
    ↳ 🧠 Sub1_Ses2_B2.bdf
    ↳ 🧠 Sub2_Ses1_B1.bdf
    ↳ 🧠 Sub2_Ses1_B2.bdf
    ↳ 🧠 Sub2_Ses2_B1.bdf
    ↳ 🧠 Sub2_Ses2_B2.bdf

The design would be:

DESIGN MATCHING PATTERN LOCATION
2 subjects (Sub1 and Sub2) Sub* 1 [files]
2 cognitive tasks GNG;NBACK 2 [folders]
2 runs (B1 and B2) B* 1 [files]
2 sessions (Ses1 and Ses2) Ses* 1 [files]

Hence, based on the example below, the prompt should be filled accordingly:

Regarding the last entry, you have the possibility to load an excel file that you have manually populated.

As such, you will see the following windows:

The Excel file should be structured the same way as the tables below (when selecting "Autogenerated" instead).

Here is an exemple of file formatting (the two sheets DATA and DESC are mandatory!):

Excel DATA sheet

Excel DESC sheet

Participant information and variables description

Based on your reply to the last entry of the BIDS design parameters prompt, you may see two tables pop-up:

DATA table

This sheet contains file-specific information that will be exported as part of the BIDS metadata (e.g. Task, session, headcircumference, etc).
You can add as many columns as desired, but AVOID MODIFYING THE EXISTING VARIABLES NAME (i.e. first line of the table).

Once you are satisfied with your results, close the table (press on the X).

DESC table

This sheet contains:

  • The name of the the variables included in the previous table
  • A short description of each variable
  • The specification of the levels for each categorical variables. For e.g. if you have 2 sessions (1 & 2), you can here rename them as Pre and Post.

Once you are satisfied with your results, close the table (press on the X).

Loading existing EEGLAB study

Specify whether you would like to load an existing study or create a new one (for more information on EEGLAB STUDY see the EEGLAB wiki).

EEGLAB GUIs

This part relates to the EEGLAB BIDS plugin GUIs for which detailed information can be found here: wiki page.

Task information

This first GUI will be autopopulated with BioSemi 64-electrodes cap information used in our laboratory.

Participant information

Optional: this second GUI will only pop-up if you decided to go with the EEGLAB GUI method [2] in the BIDS design parameters prompt.

Event information

This last GUI will always pop-up to help you specify information related to the EEG events.
For additional information, please refer to the BIDS plugin official wiki page.

BIDS export error

Finally, this error may pop-up sometimes will trying to export the BIDS metadata.
Here, MATLAB cannot delete previous files contained in the BIDS_EXPORT folder due to administrator privileges issues.
To fix this issue you need to:

  • Run MATLAB with administrator privileges or
  • Manually delete all files/subfolders contained in the BIDS_EXPORT folder.

BIDS export validation

👷 Under construction since the output is currently very messy in MATLAB.
I recently opened an issue.
In the mean time, this step can be performed outside MATLAB using BIDS-validator online validation system.

Outputs

Once the BIDS metadata generation is done, your folders structure will look as following (only files ending with an asterisk * are new):

📁 [Functions]
📁 [ChanLocs]
 ↳ ⚙️  biosemi64.locs
 ↳ ⚙️  biosemi128.xyz
📁 [TEMP]*
 ↳ 🧠  Sub1_Ses1_B1.set*
 ↳ 🧠  Sub1_Ses1_B2.set*
 ↳ 🧠  ...
📁 [BIDS_EXPORT]*
 ↳ 📁 [code]* 
 ↳ 📁 [stimuli]*
 ↳ 📁 [sub-001]*  
    ↳ 📁 [ses-01]*  
       ↳ 📁 [eeg]*  
    ↳ 📁 ...
 ↳ 📁 [sub-002]*  
    ↳ 📁 ... 
 ↳ 📃 dataset_description.json*
 ↳ 📃 participants.json* 
 ↳ 📃 participants.tsv*
📃 Study.study*
📃 BIDS.m
📃 LICENSE.md
📃 README.md
📃 ParticipantInfo_BIDS.xlsx*

  • The BIDS_EXPORT 📁 folder and its subfolders contain all the BIDS metadata. \

    • In the code 📁 subfolder you should now manually place your analyses code (!) \
    • In the stimuli 📁 subfolder you should now manually place anything related to stimuli (e.g. cognitive tasks, stim. randomization sheets, etc) (!) \

  • Finally, the TEMP 📁 folder is linked to the Study.study 📃 file and represent respectively the study data and information. Since the folder can be very heavy, you can delete it after successfully running the script if you don't need the study for other purposes.

Clone this wiki locally