# BIDS support within QuNex

[Brain Imaging Data Structure (BIDS)](https://bids.neuroimaging.io) is a standard for organizing and describing MRI and other neuroscientific datasets. Its aim is to enable easier sharing and reuse of data across the neuroscientific community.

QuNex suite uses a specific naming convention and folder structure for the neuroimaging and supporting data, which allows for BIDS integration. As exceedingly higher number neuroimaging datasets are shared using BIDS specification, QuNex is designed to support BIDS by providing functionality that allows importing of BIDS compliant data to the QuNex data structure. In the near future, QuNex will also support generation of BIDS compliant datasets from data present in the QuNex data structure.

Currently, importing of datasets is implemented by [`import_bids`](../../api/gmri/import_bids.rst) and `map_bids2nii` commands. Please see the relevant section in [Preparing the study folder](../UsageDocs/PreparingStudy) and [onboarding data](../UsageDocs/OnboardingNewData), and the in-line help for the two commands, accessible by running `qunex ?import_bids` and `qunex ?map_bids2nii`.

To make full use of the information provided by BIDS specification, the dataset should conform to the current [BIDS specification](https://bids-specification.readthedocs.io/en/stable/). To import the data and process it through the HCP Pipelines, the following minimal requirements have to be met:

* image files need to be present in NIfTI format and named according to BIDS specification
* key information about images need to be recorded

These are presented in the following sections.

## Folder structure

The following folder structure and naming is expected for a multi session dataset:

``` bash
bids_study
├── sub-01
│   ├── ses-A
│   │   ├── anat
│   │   │   ├── sub-01_ses-A_T1w.nii.gz
│   │   │   └── sub-01_ses-A_T2w.nii.gz
│   │   ├── func
│   │   │   ├── sub-01_ses-A_task-rest1_bold.nii.gz
│   │   │   ├── sub-01_ses-A_task-rest1_bold_sbref.nii.gz
│   │   │   ├── sub-01_ses-A_task-rest2_bold.nii.gz
│   │   │   ├── sub-01_ses-A_task-rest2_bold_sbref.nii.gz
│   │   │   ├── sub-01_ses-A_task-flanker_bold.nii.gz
│   │   │   └── sub-01_ses-A_task-flanker_bold_sbref.nii.gz
│   │   ├── fmap
│   │   │   ├── sub-01_ses-A_phase1.nii.gz
│   │   │   └── sub-01_ses-A_phase2.nii.gz
├── sub-01
│   ├── ses-B
...
```

The following folder structure and naming is expected for a single session dataset:

``` bash
bids_study
├── sub-01
│   ├── anat
│   │   ├── sub-01_T1w.nii.gz
│   │   └── sub-01_T2w.nii.gz
│   ├── func
│   │   ├── sub-01_task-rest1_bold.nii.gz
│   │   ├── sub-01_task-rest1_bold_sbref.nii.gz
│   │   ├── sub-01_task-rest2_bold.nii.gz
│   │   ├── sub-01_task-rest2_bold_sbref.nii.gz
│   │   ├── sub-01_task-flanker_bold.nii.gz
│   │   └── sub-01_task-flanker_bold_sbref.nii.gz
│   ├── fmap
│   │   ├── sub-01_phase1.nii.gz
│   │   └── sub-01_phase2.nii.gz
├── sub-02
│   ├── anat
...
```

In both cases it is assumed that high-resolution T1w and T2w images, multiband BOLD images for two resting state runs and one flanker task run with a corresponding single-band reference image (`_sbref`), and two spin echo images with different phase encoding directions were all acquired.

If single-band BOLD images were not acquired then the dataset could be:

``` bash
bids_study
├── sub-01
│   ├── anat
│   │   ├── sub-01_T1w.nii.gz
│   │   └── sub-01_T2w.nii.gz
│   ├── func
│   │   ├── sub-01_task-rest1_bold.nii.gz
│   │   ├── sub-01_task-rest2_bold.nii.gz
│   │   ├── sub-01_task-flanker_bold.nii.gz
│   ├── fmap
│   │   ├── sub-01_phase1.nii.gz
│   │   └── sub-01_phase2.nii.gz
├── sub-02
│   ├── anat
...
```

## Key images information

The data can be imported to QuNex even without json sidecar files. The following information has to be available to process the images successfully:

### Structural images

* Dwell Time in seconds
* Readout Direction

### Functional images

* Echo Spacing in seconds
* Phase Encoding Direction
* TR / Repetition Time in seconds

### Spin-echo image pair

* Echo Spacing in seconds
* Phase Encoding Direction

### DWI images

* Echo Spacing in milliseconds
* Phase Encoding Direction

## Supporting software

To convert images from DICOM to NIfTI, we recommend the use of the latest version of [dcm2niix](https://github.com/rordenlab/dcm2niix) with enabled extraction of metadata to JSON sidecars (`-b y` command option, with `-ba y` for anonymization of metadata).

For a more comprehensive list of software supporting conversion to BIDS format, consult the [BIDS website](http://bids.neuroimaging.io).

## Behavioral data

Upon import of the BIDS dataset, the behavioral and participant specific data present in the `<bids_study>/participants.tsv` and `<bids_study>/phenotype/*.tsv` files is parsed and split so that data belonging to a specific participant is mapped to that participant's sessions `behavior` folder (e.g. `<QuNex study folder>/sessions/s14_01/behavior/masq01.tsv`). In this way the session folder contains all the behavioral data relevant for that participant.