Hands on brain dynamics on the connectome sinergia summer school: 2021 Oct 11-12

Tutorial 1: Brain Imaging Data Structure

Overview

Teaching: 40 min
Exercises: 20 min
Questions

  • What is BIDS?

  • Why BIDS?

  • How a BIDS dataset can be made?

  • How a BIDS dataset can be query?

Objectives

  • Introduction to BIDS and its ecosystem of tools

  • Get familiar with the summerschool dataset that will be used throughout most of the tutorials

Hand over the stage to Sebastien.

Prerequisites

For best learning outcome, it is essential to have a basic understanding of:

If not, we recommend you to follow the lessons for the unix shell and for Programming in Python made by Software Carpentry.

Although not essential it is also helpful to have an understanding of:

Introduction

The dataset that will be used throughout most of the tutorials of the summer school follows the Brain Imaging Data Structure (BIDS) standard. This tutorial introduces you to BIDS, its eco-system, and the dataset itself.

Tutorial outline

What is BIDS?

Selected external lesson Material

  1. Krzysztof Gorgolewski’s overview of BIDS and reproducibility: Towards open and reproducible neuroscience in the age of big data
  2. The BIDS Specification
  3. “The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments” (Gorgolewski et al 2016) doi:10.1038/sdata.2016.44
  4. Arnaud Delorme’s presentation of BIDS-EEG: The BIDS Neuroimaging Data Format for EEG
  5. ReproNim lesson: FAIR data module

Why BIDS?

  1. Data Sharing and Reproducibility: BIDS facilitates data sharing to a greater extent. By providing a consistent and well-specified way to organize and document neuroimaging data and metadata, it prevents not only the situation in which you spend hours in making sense of the data shared by a colleague or your past-self, but also the situation in which you spend hours in finding pertinent information. The improvement of data sharing induced by BIDS allows us to better assess and reproduce others’ experimental findings.

  2. Ecosystem of tools: A number of tools have been developed around BIDS such as the BIDS-validator, to automatically check datasets for adherence to the specification, OpenNeuro, as a open database for sharing datasets structured following BIDS, pybids a Python library that centralizes interactions with BIDS formatted datasets, or the so-called “BIDS Apps”, a collection of portable neuroimaging analysis pipelines that take BIDS datasets as input.

  3. Code sharing: By developing a tool that can handle BIDS formatted datasets, you create at the same time a BIDS-app that has the potential to be applicable to a large range of users as BIDS becomes increasingly popular.

Suggested external reference

  1. Andy’s Brain Book

How BIDS is different from the existing solutions

Getting familiar with BIDS and the summer school dataset

The dataset that will be used in this tutorial and throughout most of the tutorials of the summer school consists of a sample of the VEPCON dataset, a multimodal neuroimaging dataset created by our consortium. It is located in $HOME/Data/ds003505 in the virtual machine provided for the summer school.

It follows the BIDS standard and provides raw data of high-density EEG, structural MRI and diffusion weighted images (DWI) recorded for the first of the 20 participants. Visual evoked potentials were recorded while the participant discriminated briefly presented faces from scrambled faces, or coherently moving stimuli from incoherent ones. You can find below an overview of the dataset content along with a short description of each file.

$HOME/Data/ds003505                         
├── dataset_description.json                -> Describes briefly the dataset in JSON format
├── participants.tsv                        -> Table file that stores demographical information of the participants
├── participants.json                       -> Describes the columns of participants.tsv table file
├── CHANGES                                 -> Describes changes between dataset versions   
├── README                                  -> Describes the dataset in more details in Markdown format
└── sub-01
│   ├── anat
│   │   ├── sub-01_T1w.nii.gz               -> Raw T1w MRI stored in Nifti format
│   │   └── sub-01_T1w.json                 -> Describes acquisition parameters related to the Nifti image
│   ├── dwi
│   │   ├── sub-01_dwi.nii.gz               -> Raw diffusion MRI stored in Nifti format
│   │   ├── sub-01_dwi.json                 -> Describes acquisition parameters related to the Nifti image
│   │   ├── sub-01_dwi.bval                 -> Describes the b-value for each diffusion gradient direction
│   │   └── sub-01_dwi.bvec                 -> Describes the diffusion gradient directions
│   └── eeg
│       ├── sub-01_coordsystem.json         -> Describes coordinate system, units, fiducials, anatomical landmarks location
│       ├── sub-01_electrodes.tsv           -> Location of electrodes expressed in the coordinate system and units described in _coordsystem.json file
│       ├── sub-01_task-faces_channels.tsv  -> List the channels
│       ├── sub-01_task-faces_eeg.bdf       -> Raw EEG data in .bdf format
│       ├── sub-01_task-faces_eeg.json      -> Describes acquisition parameters of the raw EEG data
│       ├── sub-01_task-faces_events.tsv    -> Table file that describes each event 
│       └── sub-01_task-faces_events.json   -> Describes the columns of the _events.tsv table file
└── derivatives                             -> Stores the derivatives i.e. the data generated during the tutorials

External supporting material

  1. VEPCON preprint: “Source imaging of high-density visual evoked potentials with multi-scale brain parcellations and connectomes” (D. Pascucci, S. Tourbier et al 2020) doi: 10.1101/2021.03.16.435599

In this exercise you will work through the creation of a BIDS dataset using a sample of the summerschool dataset that was made not BIDS-compliant.

Exercise 1: Create a BIDS-compliant dataset (click on the arrow to open)

  1. Go to the $HOME/Data/ds003505-sample directory that stores a modified version of the dataset that will be used during most of the tutorials of this summer school, created for the purpose of this exercise.
  2. Working with the BIDS material provided (above) and information from the data publication in Nature Scientific Data and re-work the base dataset to conform to BIDS.
  3. As you work through this exercise - you can use the BIDS validator to check your progress (must use Google Chrome or Firefox).

Solution (click on the arrow to open)

To be compliant with BIDS, the files of the sample dataset should be named and structured in folders as follows:

tree $HOME/Data/ds003505-sample-solution

├── CHANGES
├── README
├── dataset_description.json
├── participants.json
├── participants.tsv
└── sub-01
    ├── anat
    │   ├── sub-01_T1w.json
    │   └── sub-01_T1w.nii.gz
    └── dwi
        ├── sub-01_dwi.bval
        ├── sub-01_dwi.bvec
        ├── sub-01_dwi.json
        └── sub-01_dwi.nii.gz

In this exercise you will work through the interaction with the summerschool sample dataset in Python using the pybids library.

Exercise 2: Interact with the summerschool dataset in Python (click on the arrow to open)

  1. Open a terminal in the VM
  2. Launch ipython
  3. Import the BIDSLayout class from the pybids library
  4. Print a general overview of the object (hint: use the print() method)
  5. Initialize a BIDSLayout object with the path of summerschool sample dataset
  6. Use the get() method on the created object to get the path of the T1w image of sub-01 Hint: check the pybids tutorial)
  7. Similarly, use the get() method on the created object to get the path of the diffusion image of sub-01, but this time, by providing the argument in a python dictionary. Hint: use the ** operator to pass a number of arguments in the form of a key/value dictionary to a function.
  8. List the available EEG tasks (hint: use get_tasks())

Solution (click on the arrow to open)

# Import the BIDSLayout class from pybids
from bids import BIDSLayout

# Create the BIDSLayout object representing the summerschool sample dataset
layout = BIDSLayout("$HOME/Data/ds003505")

# Get the list of T1w images available for sub-01
t1_files = layout.get(subject='01', extension='nii.gz', suffix='T1w', return_type='filename')
print(t1_files)

# Get the list of DWI images available for sub-01
dwi_query = {
    "subject": "01",
    "extension": "nii.gz",
    "suffix": "dwi",
    "return_types": "filename"    
}
dwi_files = layout.get(**dwi_query)
print(dwi_files)

# Get the list of EEG tasks available 
eeg_tasks = layout.get_tasks()

How can I convert to BIDS?

For MRI, you will need to have access to raw data (e.g. dicoms) in order to perform the conversion. There are several different packages that can be used to accomplish this, such as dcm2bids, heudiconv/reproin, bidscoin, bidskit.

For EEG, you will need to have access to raw data in order to perform the conversion. There are several different packages that supports this process, such as mne-bids, Fieldtrip data2bids, bids-matlab-tools EEGLab addon, Brainstorm, BrainVision bv2bids.

For physiological recordings, there exist physio2bids and bidscoin for data recorded with Siemens MRI scanner, and phys2bids for data recorded by AcqKnowledge (BIOPAC) and Labchart (ADInstruments).

Admittingly, most BIDS converters require a bit of user input and work. A number of great tutorials are available online to help you getting started.

Selected external tutorials

MRI data tools

EEG data tools

Physiological data tools

Additional materials

Key Points