Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/cimcyc/bids-converter-mri-matlab

This repository provides a set of functions and scripts designed to facilitate the creation of BIDS-compliant datasets and the conversion of DICOM files to NIFTI format.
https://github.com/cimcyc/bids-converter-mri-matlab

bids matlab mri

Last synced: 21 days ago
JSON representation

This repository provides a set of functions and scripts designed to facilitate the creation of BIDS-compliant datasets and the conversion of DICOM files to NIFTI format.

Awesome Lists containing this project

README 

          
# DICOM to BIDS Converter

---

This repository provides a set of functions and scripts designed to facilitate the creation of BIDS-compliant datasets and the conversion of DICOM files to NIFTI format.



## Installation



- The installation of this converter consists of downloading the repository (or cloning it directly from GitHub) into the desired local directory.

- Once downloaded, Matlab should be launched, and the working directory set to the folder `bids-converter-mri-matlab`. At this point, the environment will be ready to perform conversions of raw DICOM files into BIDS-compliant NIFTI datasets.

- **Important:** This software relies on the `dcm2niix` package to perform the conversion from DICOM to NIFTI. The package is widely used by software such as MRIcroGL and may already be available on the system. If it is not present, installation instructions are provided in the [official repository](https://github.com/rordenlab/dcm2niix?tab=readme-ov-file#install). The package is supported on Windows, macOS, and Linux.



## Initial Configuration



The converter requires the definition of several configuration parameters to adapt the process to a specific dataset. These parameters are located in the folder `cfg` inside `bids-converter-mri-matlab`. Two configuration files are included:



- `configurationFile.m`

- `datasetDescription.m`



These files are the only ones that need to be modified before running the conversion.



### 1. Dataset-Level Metadata: `datasetDescription.m`



This file contains the general metadata that describes the BIDS dataset to be generated. It must be configured once per dataset, regardless of the number of participants included. The fields in this file include information such as author names, acknowledgments, dataset DOI, and other metadata. Each parameter is defined as either mandatory or optional, as indicated in the file comments. For example:



```matlab

%% Authors (OPTIONAL) [type: array of strings]

% Description: List of individuals who contributed to the creation/curation 

% of the dataset.



datasetDescription.Authors = {

    'Joanne Walker';

    'William Walker'

    };

```



The information specified in this file is automatically incorporated into the mandatory `dataset_description.json` file, as required by the BIDS standard.



### 2. Participant-Level Configuration: `configurationFile.m`



This file contains configuration parameters required to define participant-specific aspects of the conversion. It includes identifiers, file format specifications, input and output directories, and additional metadata.



The following elements must be specified:



**BIDS Participant Identifier**  

Participant identifiers must follow the BIDS convention: the prefix `sub-` followed by an alphanumeric code.

```matlab

cfg.subjectId = 'sub-001';

```



**BIDS Session Identifier**  

For studies with multiple acquisition sessions (e.g., pre- and post-intervention), a session label must be included. The session name must follow the BIDS convention: the prefix `ses-` followed by a session code. For example:

```matlab

cfg.sessionName = 'ses-pre';

```

If only one session is present, this parameter must remain an empty string:

```matlab

cfg.sessionName = '';

```



**BIDS Output Data Format**  

This parameter specifies the format of the generated NIFTI files (compressed or uncompressed). The supported values correspond to the options available in the `dcm2niix` conversion engine:

```matlab

cfg.dataFormat = 'y';



% - 'n' for single nii uncompressed.

% - 'y' for single nii.gz compressed.

% - etc ...

```



**BIDS Output Directory**  

Defines the output directory where the converted BIDS dataset will be stored. It also specifies whether auxiliary files such as `dataset_description.json`, `README`, license, or changelog should be generated:

```matlab

cfg.outputDirectory = 'C:\Users\David\Desktop\bids';

cfg.generateDatasetDescriptionFile = true;

cfg.generateREADMEFile = true;

cfg.generateLicenseFile = true;

cfg.generateChangesFile = true;

```



**Raw DICOM Directory**  

Specifies the root directory containing the original DICOM data. For Siemens scanners, the directory structure typically includes subfolders for each modality (structural, diffusion, functional, field maps, etc.):

```matlab

cfg.rawDICOM = ['C:\Users\David\Desktop\raw\NeEpaaq_1\Alfonso_Caracuel_Rm - 1'];

```



**Definition of Data to be Converted** 

This step is one of the most important in the entire process. At this stage, the directories to be converted into BIDS format must be defined. Depending on the acquisition protocol, the data may be organized into subfolders, some containing structural data and others containing functional data organized in separate folders for different tasks/runs, etc. Clearly specifying which subfolders are to be converted and the contents of each of them is essential to ensure a correct conversion to the BIDS standard.



The following example illustrates a simple case where the script is instructed to convert the T1 and T2 data of a participant:



***Example: Structural Data***

```matlab

dcm{1}.folder = [cfg.rawDICOM filesep 't1_mprage*']; 

dcm{1}.dataType = 'anat';

dcm{1}.modality = 'T1w';



dcm{2}.folder = [cfg.rawDICOM filesep 't2_tse*']; 

dcm{2}.dataType = 'anat';

dcm{2}.modality = 'T2w';

```

As can be observed, the variable ``dcm`` is defined as a cell array, with one cell corresponding to each subfolder to be converted. For instance, to specify the conversion of T1 DICOM data, the first cell `dcm{1}` is used, while the second cell `dcm{2}` is used for T2 data.



Each cell contains a structure with multiple fields that must be specified to describe the corresponding data. Examples include the full path to the subfolder (`dcm{1}.folder`), the type of data to be converted (`dcm{1}.dataType`), and the modality (`dcm{1}.modality`).



A simple example for diffusion (DTI) data is shown below:



***Example: Diffusion Data***

```matlab

dcm{3}.folder = [cfg.rawDICOM filesep 'ep2d_diff_mgh_1_39*'];

dcm{3}.dataType = 'dwi';

dcm{3}.modality = 'dwi';

```

Depending on the type of data to be converted, additional fields must be configured. For example, for task-based functional data, the name (or names) of the tasks performed by the participant must be specified.



***Example: Task-Based or Resting-State Functional Data***  

```matlab

dcm{4}.folder = [cfg.rawDICOM filesep 'task1*'];

dcm{4}.dataType = 'func';

dcm{4}.modality = 'bold';

dcm{4}.task = 'task-task1';

dcm{4}.events = 'events.tsv';



dcm{5}.folder = [cfg.rawDICOM filesep 'task2*'];

dcm{5}.dataType = 'func';

dcm{5}.modality = 'bold';

dcm{5}.task = 'task-task2';

dcm{5}.events = 'events.tsv';



dcm{6}.folder = [cfg.rawDICOM filesep 'task3*'];

dcm{6}.dataType = 'func';

dcm{6}.modality = 'bold';

dcm{6}.task = 'task-task3';

dcm{6}.events = 'events.tsv';

```

In this example, the configuration specifies the conversion of data from three tasks performed by the participant during the experiment. The task name must be defined in the field `dcm{x}.task` and must be preceded by the prefix `task-` to comply with the BIDS standard. For resting-state data, the structure remains the same, although the BIDS specification recommends using the task name `task-rest`. In addition, the configuration indicates that the data type is functional and that the modality is BOLD.



The field `dcm{x}.events` must specify the name of the `.tsv` file containing the event information, in cases where task-based data are included.



***Example: Functional Data with Multiple Runs***  

For functional protocols with multiple runs, the parameter `run` must be included in the configuration:

```matlab

dcm{4}.folder = [cfg.rawDICOM filesep 'gonogo_run1*'];

dcm{4}.dataType = 'func';   

dcm{4}.modality = 'bold'; 

dcm{4}.task = 'task-gonogo';

dcm{4}.run = 'run-1'; 

dcm{4}.events = 'events.tsv';



dcm{5}.folder = [cfg.rawDICOM filesep 'gonogo_run2*'];

dcm{5}.dataType = 'func';   

dcm{5}.modality = 'bold'; 

dcm{5}.task = 'task-gonogo';

dcm{5}.run = 'run-2';

dcm{5}.events = 'events.tsv';



dcm{6}.folder = [cfg.rawDICOM filesep 'gonogo_run3*'];

dcm{6}.dataType = 'func';   

dcm{6}.modality = 'bold'; 

dcm{6}.task = 'task-gonogo';

dcm{6}.run = 'run-3';

dcm{6}.events = 'events.tsv';

```



***Example: Field Map Data***  

In many protocols, field map acquisitions are included, which are subsequently used during data preprocessing to correct artifacts caused by magnetic field inhomogeneities introduced by the scanner. The following example illustrates how these acquisitions can be specified for conversion to the BIDS format:

```matlab

dcm{7}.folder = [cfg.rawDICOM filesep 'gre_field_mapping_*'];

dcm{7}.dataType = 'fmap';

dcm{7}.modality = 'fieldmap';

```



## 3. Execution



Once the configuration file for a participant is defined, the script `bidsConverter.m` can be executed within Matlab. Running the script will initiate the conversion of the DICOM data into BIDS-compliant format.



***Note:*** At present, the software is designed to be executed on a per-participant basis, ideally immediately after data acquisition. A multi-participant version of the tool is currently under development.