Home

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

• autoBIDS
  • Downloading the repository
  • Table of Contents
  • Getting Started
    • Loading Raw EEG files
    • Loading marker files (optional)
    • Loading channels location file
    • Preprocessing parameters
    • BIDS design parameters
    • Participant information excel file
      • DATA sheet
      • DESC sheet
    • Loading existing EEGLAB study
    • EEGLAB GUIs
      • Task information
      • Participant information
      • Event information
    • BIDS export error
    • BIDS export validation
  • Outputs

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 based on the provided raw EEG files names.
It is divided into 4 categories for which the same principles of matching patterns apply:

• SUBJECTS: the unique name of the subjects in your files/folders structure (mandatory)
• 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 (optional)
• SESSIONS: The unique name of the within-subject factor session in your files structure, if any (optional)

The concept is for each of the category to specify:

• The unique identifier
• Whether this identifier can be found in files [1], folders [2] or does not exist if not applicable [0]

Finally, the last entry of the prompt enables you to either let the script autopopulate an excel file to give detailed task and participant information (see prompts below) [1] which is the recommended method, or use EEGLAB GUIs [2], which will be much slower.

To better illustrate these explanations 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 related to this example is the following:

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 have been filled accordingly:

Participant information excel file

Based on your reply to the last entry of the BIDS design parameters prompt, you may see an excel file pop-up.
This relates to the participant information that will be exported as part of the BIDS metadata.
You have the possibility to adjust the automatically filled information (based on previous prompt) and even add or rename columns.
Importantly, there will be 2 sheets in the excel file:

DATA sheet

This sheet contains information specific to each provided file such as Task, session, headcircumference, etc. If you make changes to the DATA sheet columns (add and/or modify columns), YOU NEED TO REPORT THESE CHANGES IN THE DESC SHEET BELOW !

DESC sheet

This sheet contains in each column:

• The name of the variables corresponding to the column names in the DATA sheet (SAME ORDER)
• The description of each included variable
• The specification of the levels for each categorical variables. For e.g. if you have coded gender as F and M, you can here specify that it corresponds respectively to Female and Male. The levels should be specified in the alphabetic order (or natural oder if containing letters and numbers).

Once you are satisfied with your results, press the OK button.

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 informaion, 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.