Hello, my name is Arnaud Delorme, and this is a presentation about the using
the Brain Imaging Data Structure EEGLAB plugin to import and export BIDS data.
If you want to know what BIDS is, there is another presentation on this topic and I
put a link in the description. I advise that you watch this other presentation first, especially
the part concerning the BIDS example file. In this presentation, first I will show
you how to import BIDS data into EEGLAB and then how to export raw data to BIDS.
This assumes you have installed EEGLAB of course. I put a link to download EEGLAB in
the description. After starting EEGLAB, we need to install or update the BIDS EEGLAB
plugin. For this you go to the EEGLAB plugin manager which is this menu item.
Then you find the BIDS plugin. You can also search for BIDS using the search feature on the top
right corner. Once you have found it, you simply install it and this will add
a BIDS submenu item to the EEGLAB File menu as we will see in a second.
So let's start with importing some BIDS data. Importing is simpler than exporting. Also
importing BIDS data will allow us to quickly review the BIDS format.
After we import this data, I will show you how to export raw data into BIDS on a simplified example.
So this is the dataset we are going to use. It is available for public download on
the OpenNeuro website. Also, I put a link in the description below. You can look at the
files and also download the whole dataset as a ZIP archive. NEMAR is an extension of OpenNeuro
for the EEG and MEG community, which we are building in collaboration with OpenNeuro.
In this experiment, participants are performing an oddball task, where they press a button whenever
they hear an oddball sound. I am going to play a sample audio recording in a second. So you have
standard stimuli which are frequent and these will be the first 3, then occasionally you have oddball
or noise stimuli. The task of the participants is to press a button when they hear the oddball.
The noise stimuli are just distractor on which you are not supposed to respond. So let's hear it.
In this case, we have 70% of standard, 15% of oddball, and 15% of noise stimuli.
Mr Delorme, Mr Delorme Yes me from the past.
This task makes no sense to me. How can you study cognition with boring beeps and boops.
Don't you want to put people in virtual reality or something a little more challenging?
Well, historically, these are the types of task we have been using in psychophysics.
It has its value but I agree that these days, we can also do experiments
with richer environments. Anyway, let's pursue.
Once you have downloaded this dataset, let's review what it contains.
The BIDS video - link in the description - goes into further detail into this topic,
so I am going to go fast here. The Brain Imaging Data Structure or BIDS
is a way to name your folder and your files for an experiment, as well as adding a collection
of formatted text files, so it follows the BIDS specifications.
The advantage of using BIDS is that EEGLAB can automatically import the BIDS folder
structure as an EEGLAB STUDY, which means as a group of datasets from multiple subject
that is readily available for group processing. EEGLAB can also import additional event and
channel information contained in BIDS files that is often not available in the raw EEG data files.
So here is the folder we have just downloaded and we are going to look at some files first
participants.tsv so it contains gender and age columns and one row per participant. Then we
have the subject folder and EEG subfolder. So here we have three runs and three sets of
files. We are just going to look at one of the set. For example the channel file which contains
channel labels and channel types. And then we have the electrode file which contains coordinates.
If you want to know why they are different files you can look at the other BIDS video,
the first [video] of this series. Then we have the event file which contains a collection of events,
one per row - here we have many. Then different columns: value, trialtype, and then onset which
is the beginning of the event. And so now we are going to just import this dataset, so we
select the import menu and here we are going to select these two check boxes to overwrite events.
So, when these checkboxes are selected, EEGLAB will import the raw EEG data files, but will
overwrite the event and channel information with the information stored in the BIDS files.
If the dataset you downloaded is well formatted in BIDS, it will rename events,
add channel locations and channel types, etc...
You may also select the BIDS field you may want to import to define EEGLAB data types.
The two choices are BIDS event values and BIDS event trial type.
So you need to look at the BIDS event file – as we have done previously – to see which
one makes the most sense for you based on the analysis you will want to do with that data.
So here we map EEGLAB event types to the
value BIDS field. Then we press OK. Now the BIDS data is imported as an EEGLAB STUDY.
There is another video on how to process this data in EEGLAB and I put the link in the description.
So we have imported some BIDS data. Now, let's try to export some data.
So I have this raw data I have prepared. It is the same data as the one
we imported but here I only have 2 subjects instead of 13.
I put a link to the raw data files on the top of this slide and also in the description.
First we are going to import the raw data. I will import 6 data files from 2 subjects with
3 runs per subject. Both EEGLAB and BIDS support runs and sessions for subjects. Basically a run is
when you have blocks in an experiment and when the data from each block is stored in a separate file.
Sessions are used when the data is collected on different days or when there is a break
that involves removing the EEG cap. There is no hard definition. This is what I like to use,
and I think most EEG researchers would agree. For runs in EEG, we are not removing the cap,
but for EEG sessions we are removing the cap. So let's import these 6 files. These are BDF
files - which is a specific research amplifier and data collection program.
I am selecting them here, and then simply agreeing to import them with the default options.
I am also agreeing to save the files on disk as EEGLAB datasets. Note that here I can import
several files at once, but in older EEGLAB version, you have to import them one by one.
Now, we are going to create a STUDY with these files. We enter subject and run information
then press OK. Now we have the raw data files imported in EEGLAB.
Before we enter BIDS information, let's assign locations to our electrodes.
In the raw data files, channel locations are often not available.
In EEGLAB, we can simply use the "Channel location" menu item,
and based on the channel labels, it will automatically use template locations.
There are several choices for the template. Here I am using the template BEM channel location,
which are usually preferred compared to the default spherical channel coordinates.
We will probably change the default in the near future.
Channel information will be exported along with the BIDS dataset, so researchers
who import your data will already have electrode locations for your datasets.
Now, moving on to BIDS, let's first enter task and experiment information. So this is this menu item.
So here it is pre-filled, but obviously you would need to fill that information yourself.
So we have a dataset name, then a dataset name with no space.
Then we have a short description that will be stored in the README file. Then
we have description of the experiment, and instructions given to participants.
Then we have authors, publication reference if any, and lab information. On the right column,
we have amplifier and EEG cap characteristics. Most of the fields on this form are optional,
but obviously, it will be harder for other people to use your data if there is missing information.
Second let's enter participant information. So this is this second menu item.
So here I have two participants and one row per subject.
It am going to enter gender and age information.
For gender, I can also go in the description table and indicate what F means. If you remember the
BIDS video, the participant information will be stored in the participant.tsv file that contains
one row per subject and the column information will be stored in participant.json file.
We can also import a text or excel file with additional columns. So here I have a file
with some additional demographic information. So I press the import button and select the file,
then I need to select the participant ID column and this column must contain the
same participant ID as I already have. I can also select columns for the pre-determined
BIDS column, and I can select columns which will be added to the participant file.
Then, let's look at the events. This is the next menu on the list.
So here I select the EEGLAB event fields for each BIDS event column. If it is empty, it is fine.
So onset corresponds to the latency field of EEGLAB although this field is in sample so
it is converted to seconds here from the sample field. Then we have BIDS event duration usually
associated with the EEGLAB duration field when present. Then we have the BIDS sample field
which is equivalent to the EEGLAB latency field. Then we have trial type which can be for example
stimulus or response. Then we have response time, for example when you have a reaction
time to a stimulus. Then we have stim file which may contain the name of a stimulus file stored in
the "stimuli" BIDS folder. Finally, we have the value field which is the value associated with
the event. Here our events can take value 1, 2, 3, 4 and 8 and they are stored in the "type" field of
EEGLAB. We are also going to define these events. So we have response corresponding to type 1. We
have type 2 which is standard stimuli which are sounds at 500 hz for 60 ms. We have type 3 which
we can ignore here - this is glitch and there are very rare. We have type 4 which are oddball
stimuli which are sounds at 1000 hz for 60 ms. And we have type 5 which is white noise for 60 ms.
We can also add one or more custom field. Here I am adding the field test.
And for this custom BIDS field I am selecting the EEGLAB field "edftype".
So we are now done entering all that information.
Note that the information is stored along with the dataset, so I advised that you resave the
datasets when you are done editing BIDS documentation. We are ready to export.
So we select the export menu item in the BIDS sub-menu.
Here it is asking us where we want to save the exported data,
the type of license we want to use and changes since the last published export. For example,
you might have exported a first time and published your data but some information was missing, so you
are now exporting the BIDS dataset a second time. You can leave that empty. You also have the
option here to click on buttons to review or edit the task, participant
and event information. Finally, if you have not anonymized your subject ID, for example,
if you have used subject's initial for their ID - which is bad practice but sometimes happen, you
can check this box to generate new anonymized ID. So you press OK and your data is being exported.
The next step is to check that your data is BIDS compliant. Since you use the EEGLAB
plugin to export it, it should always be BIDS compliant, so there will likely not be any
error. However, sometimes there are warnings. So this is the menu to call the BIDS validator.
It simply asks you for a folder to validate.
Once you press OK, it prints a report on the Matlab command line. In this case, there is a
warning message because there is only one author for the study and the BIDS validator judges that
this might be an omission. So now, you are ready to go to a data repository such as OpenNeuro,
log in with your Google account and upload your BIDS folder. It is that simple.
Note that it is also possible to use the plugin from the command line. Below is a link to a script
to export the raw data that will automatically copy or convert the raw data files, fill up task,
participants and events' information. So here we have 2 slides of an example script.
The script allows you to indicate binary raw EEG data files, here in the first section. There is
one entry per subject. If you have more than one file per subject, you can define a list of files
along with the session and run they correspond to. You can also indicate recording notes.
Then you have a section for the README file and for the content of the dataset_description file.
Then you have a section for the task information, and then a section for participants.
For participants you can define both participant columns and column description.
Then we have event description as well as event column file description. There are
special options to rename EEGLAB event types and define new trial types based on EEGLAB event types
which are not available from the graphic interface.
Then we have section for the code to include. In this case we are including the function used to
present stimuli as well as the current script. Note that exporting code is not available from
the graphic interface because you can simply copy these files to the "code" folder of the
exported BIDS archive. This is the same if you have stimuli. You can create a "stimuli" folder
and copy your stimuli into it. Most of this script is about building a parameter
list for the export function, so here at the bottom we have the export function.
So download this script and the associated data. Run it, then modify it to prepare your own data.
So I hope I hope you will use this plugin. I want to thank you for your attention,
and I hope to see you in my future videos.