iEEG data conversion
Contents
iEEG data conversion¶
Here, we briefly describe the first steps in creating an iEEG dataset in BIDS format. The process can be summarized by the following main steps:
structure your files in the proper folder hierarchy
rename files such that they adhere to the BIDS naming specification,
extract the necessary metadata from your raw data and experimental notes
add electrode-specific information needed for localization
Step 1: Folder structure¶
At the highest level, BIDS is a specification for how to structure your files in folders, and how to name files such that one can easily infer their contents. Thus, the first step is to create the proper folder/file hierarchies, which looks like this:
project/
└── subject
└── session
└── acquisition
The top level (project) of a BIDS folder must contain a dataset_description.json
file, a README, and a CHANGES file. In addition, there are a set of sub-folders,
one per subject, that contain all data from a given subject. These must be named
according to the convention sub-<label>. Within these folders there is an
optional “session” folder (called ses-<label>) and finally a collection of
“acquisition folders” that correspond to datasets from different modalities
(such as functional imaging, EEG, and iEEG data) that corresponds to this
dataset. In our example, there is a folder called ieeg that stores all iEEG
data for the subject, for example:
iEEGProject
├── dataset_description.json
├── participants.tsv
├── README
├── CHANGES
├── sub-01
│ ├── anat
│ │ └── sub-01_T1w.nii.gz
│ └── ieeg
│ ├── sub-01_task-visualtask_run-01_ieeg.edf
│ ├── sub-01_task-visualtask_run-01_ieeg.json
│ ├── sub-01_task-visualtask_run-01_channels.tsv
│ ├── sub-01_task-visualtask_run-01_events.tsv
│ ├── sub-01_electrodes.tsv
│ └── sub-01_coordsystem.tsv
├── sub-02
│ ├── anat
│ │ └── sub-02_T1w.nii.gz
│ └── ieeg
│ ├── sub-02_task-visualtask_run-01_ieeg.edf
│ ├── sub-02_task-visualtask_run-01_ieeg.json
│ ├── sub-02_task-visualtask_run-01_channels.tsv
│ ├── sub-02_task-visualtask_run-01_events.tsv
│ ├── sub-02_electrodes.tsv
│ └── sub-02_cooordsystem.tsv
...
└── visualtask_ieeg.json
Step 2. Add raw iEEG data¶
Once a folder hierarchy is defined, the folders can be populated with the
correct files. Here we focus on the files relevant for iEEG data. Within the
ieeg folder, we first copy the raw iEEG data and renamed such that they adhere
to the BIDS file naming scheme. For example:
sub-<subjectlabel>_ses-<sessionlabel>_task-<tasklabel>_run-<runlabel>_ieeg.<extension>
These data are unprocessed and can have one of several file formats (for example: BrainVision and EDF formats are supported, NWB, EEGLab and MEF3 formats are allowed).
Step 3. Add iEEG amplifier metadata¶
BIDS datasets should specify all of the metadata needed to analyze and
understand a dataset, and these are all contained within text-based JavaScript
Object Notation (JSON, field-value) and Tab Separated Value (TSV) metadata
files. The iEEG amplifier metadata are stored for each run in a JSON file with
the same name structure as the raw data (<raw-data-filename>_ieeg.json) and a
TSV file with amplifier metadata (<raw-data-filename>_channels.tsv).
<raw-data-filename>_ieeg.json: contains the metadata that are the same for all the data in this run, such as the task name and description, the amplifier brand, and where the experiments were performed. Download a template in the bids-starter-kit here or find the Matlab script to more automatically populate the required fields here.<raw-data-filename>_channels.tsv: The TSV file contains all the settings that differ between iEEG channels such as the units and type of channel (ECOG, SEEG, ECG, EMG, EOG and so on). Download a template in the bids-starter-kit here or find the Matlab script to more automatically populate the required fields here.
Step 4. Add electrode-specific metadata¶
In iEEG recordings, each channel in the amplifier is sampled from a specific
electrode implanted in the brain. The metadata on the type of electrodes and
their coordinates is stored in a TSV file with a row for each metallic electrode
contact (_electrodes.tsv). The names of each electrode are used in the
amplifier metadata to specify the recorded channel and reference to link these
two files. In order to interpret the position of each electrode, the coordinate
system is defined in a JSON file (_coordsystem.json). The _coordsystem.json
file specifies a reference image file, which can be an MRI, surface rendering,
standard space (for example: MNI) or operative photo, such that electrode
positions can be displayed. In addition, any raw data collected for the purpose
of localizing electrodes is stored in a corresponding anatomy folder (called
anat) that lives at the same folder level as the ieeg folder. This can
contain files like structural volume data or electrode placement photos.
Step 5. Add optional metadata¶
There are several optional data types that can be stored in BIDS. The way in which events, stimuli, continuous physiology data, and participant information are stored is the same as for BIDS MRI data. These optional metadata are stored within TSV and JSON files as well as any task-specific stimulation files (for example: photos or sounds that were presented to the subject during the task, or videos of the subject and experimental setup). Some examples are shown here:
iEEGProject
├── dataset_description.json
├── participants.tsv
├── README
├── CHANGES
├── sub-01
│ ├── stimuli
│ │ └── PresentedPhoto1.png
│ │ └── PresentedSound1.wav
│ └── ieeg
│ ├── sub-01_photo.jpg
│ ├── sub-01_task-visualtask_run-01_physio.tsv.gz
│ ├── sub-01_task-visualtask_run-01_physio.json
│ ├── sub-01_task-visualtask_run-01_stim.tsv.gz
│ ├── sub-01_task-visualtask_run-01_stim.json
...
Step 6. Validate the iEEG-BIDS data¶
In order to verify that a dataset adheres to the BIDS specification, we need to validate the structure, naming conventions, and information inside the dataset. The BIDS validator is a web- and command line-based tool that can validate whether a dataset is BIDS compliant. As a part of the iEEG extension to the BIDS specification, this validator has been updated to check for new conventions related to iEEG data.