Skip to content

BIDS integration

Jump to bottom
ksgfan edited this page Jan 20, 2023 · 19 revisions

Automagic is able to read input dataset that are organised in BIDS format as shown in the following example. The example demonstrates how the entire Automagic pipeline works. It shows how to read EEG dataset that is structured in BIDS format, preprocess them, making the quality assessment and finally export a final version to BIDS format.

Read from BIDS folder structure

If the data is in BIDS format, please select the Data in BIDS format checkbox in the Main GUI. Automagic will internally use the EEGLAB's pop_importbids and merge the EEG data, channel and event information.

The image below demonstrates how the BIDS folder structure of the input data should look like in this case.

  • if the ..._electrodes.tsv or ..._channels.tsv files are missing, Automagic will try to import the channel location information from EEGLAB template models.
  • if the reference channel (and it's coordinates) is not provided in the ..._electrodes.tsv file, Automagic will search for a reference in ..._eeg.json file. If the reference is Cz, Automagic will automatically add it and it's coordinates to EEG.chanlocs (see systemDependentParse.m). To make it work, make sure to select Add a new reference channel in the Reference Channel section (default) in Main GUI before creating a project.
  • Alternatively, if you provide a channel location file before creating a project (i.e., loc, ced, sfp, etc.), Automagic will overwrite the EEGLAB's template or the ..._electrodes.tsv information.
  • if the ..._events.tsv file is missing, Automagic will not import events to EEG.events.

Sometimes the folder structure is in BIDS format, but the .json and .tsv files are missing (e.g., events are already in EEG structure):

Automagic can deal with this situation too. However, please DO NOT select the Data in BIDS format checkbox in the Main GUI. Make sure that the channel information is already provided in the EEG structure or provide the channel location file before creating the project (i.e., loc, ced, sfp, etc.). For a list of available file formats please refer to readlocs documentation from EEGLAB.

Once your data is stored in this format, run Automagic, and create a new project with your desired configuration where you choose the data folder to be the folder containing your dataset organised in BIDS format. If the project is created successfully, you can see Automagic recognising the number of subjects and files in your data folder.

Start EEG preprocessing

Once the project is created, you can start the preprocessing by simply clicking on Run button in the Pre-processing section at the right side of the GUI. This may take a long time depending on type of the preprocessing you chose and the size of your dataset.

Interpolation and quality assessment

After preprocessing, for each file there maybe several channels marked as bad channels, and you may want to interpolate them. Clicking on Interpolate All button starts interpolation of all the channels selected to be interpolated. Additionally you can open the Data viewer or/and Quality classification window where you can observe the dataset visually and assess the quality.

Finalise and export to BIDS folder structure

Once you are totally done with preprocessing and quality assessment, if you have changed any quality assessment configuration, you should click on the Commit Rating button of the Quality classification window to finalise your study. Then by clicking Export data to BIDS format you can export results files including EEG, log files, jpegs, etc. to another selected folder in BIDS structure. The exported results will be saved in a folder called derivatives/ as specified in BIDS.

The results then will be stored in derivatives/automagic-pipeline. For each subject there will be a corresponding log file and json file. The log file is a text file describing the preprocessing steps carried out on the EEG file. The json file contains the same information but more machine readable and complied to BIDS specification. Additionally, in derivatives/code you can find the code which will reproduce the exact preprocessing with the same parameters. This code however will not reproduce changes made in the quality assessment step.

Importing the BIDS folder into Brainstorm

If you choose to continue processing your work in Brainstorm, you will only need the BIDS folder exported from Automagic. Firstly, create a Brainstorm protocol with default properties. On the Protocol tree, right-click on the Protocol name and select Import BIDS dataset from the drop-down list. In the window that appears, select the 'Folder to import' browse icon and specify the exported Automagic BIDS folder you want to analyse; if you wish to continue processing the results from Automagic, choose the derivatives\automagic-pipeline folder to be imported into Brainstorm.

Clone this wiki locally