{"id":32819451,"url":"https://github.com/cimcyc/bids-converter-mri-matlab","last_synced_at":"2026-06-28T19:31:39.706Z","repository":{"id":317350788,"uuid":"1063912915","full_name":"CIMCYC/bids-converter-mri-matlab","owner":"CIMCYC","description":"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.","archived":false,"fork":false,"pushed_at":"2025-11-06T11:37:42.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-06T13:16:30.433Z","etag":null,"topics":["bids","matlab","mri"],"latest_commit_sha":null,"homepage":"","language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CIMCYC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-25T09:32:59.000Z","updated_at":"2025-11-06T11:37:45.000Z","dependencies_parsed_at":"2025-09-30T11:39:06.689Z","dependency_job_id":null,"html_url":"https://github.com/CIMCYC/bids-converter-mri-matlab","commit_stats":null,"previous_names":["cimcyc/bids-converter-mri-matlab"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CIMCYC/bids-converter-mri-matlab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CIMCYC%2Fbids-converter-mri-matlab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CIMCYC%2Fbids-converter-mri-matlab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CIMCYC%2Fbids-converter-mri-matlab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CIMCYC%2Fbids-converter-mri-matlab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CIMCYC","download_url":"https://codeload.github.com/CIMCYC/bids-converter-mri-matlab/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CIMCYC%2Fbids-converter-mri-matlab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283190205,"owners_count":26794589,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-07T02:00:06.343Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bids","matlab","mri"],"created_at":"2025-11-07T13:02:22.629Z","updated_at":"2025-11-07T13:02:32.397Z","avatar_url":"https://github.com/CIMCYC.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DICOM to BIDS Converter\n---\nThis 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.\n\n## Installation\n\n- The installation of this converter consists of downloading the repository (or cloning it directly from GitHub) into the desired local directory.\n- 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.\n- **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.\n\n## Initial Configuration\n\nThe 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:\n\n- `configurationFile.m`\n- `datasetDescription.m`\n\nThese files are the only ones that need to be modified before running the conversion.\n\n### 1. Dataset-Level Metadata: `datasetDescription.m`\n\nThis 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:\n\n```matlab\n%% Authors (OPTIONAL) [type: array of strings]\n% Description: List of individuals who contributed to the creation/curation \n% of the dataset.\n\ndatasetDescription.Authors = {\n    'Joanne Walker';\n    'William Walker'\n    };\n```\n\nThe information specified in this file is automatically incorporated into the mandatory `dataset_description.json` file, as required by the BIDS standard.\n\n### 2. Participant-Level Configuration: `configurationFile.m`\n\nThis 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.\n\nThe following elements must be specified:\n\n**BIDS Participant Identifier**  \nParticipant identifiers must follow the BIDS convention: the prefix `sub-` followed by an alphanumeric code.\n```matlab\ncfg.subjectId = 'sub-001';\n```\n\n**BIDS Session Identifier**  \nFor 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:\n```matlab\ncfg.sessionName = 'ses-pre';\n```\nIf only one session is present, this parameter must remain an empty string:\n```matlab\ncfg.sessionName = '';\n```\n\n**BIDS Output Data Format**  \nThis 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:\n```matlab\ncfg.dataFormat = 'y';\n\n% - 'n' for single nii uncompressed.\n% - 'y' for single nii.gz compressed.\n% - etc ...\n```\n\n**BIDS Output Directory**  \nDefines 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:\n```matlab\ncfg.outputDirectory = 'C:\\Users\\David\\Desktop\\bids';\ncfg.generateDatasetDescriptionFile = true;\ncfg.generateREADMEFile = true;\ncfg.generateLicenseFile = true;\ncfg.generateChangesFile = true;\n```\n\n**Raw DICOM Directory**  \nSpecifies 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.):\n```matlab\ncfg.rawDICOM = ['C:\\Users\\David\\Desktop\\raw\\NeEpaaq_1\\Alfonso_Caracuel_Rm - 1'];\n```\n\n**Definition of Data to be Converted** \nThis 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.\n\nThe following example illustrates a simple case where the script is instructed to convert the T1 and T2 data of a participant:\n\n***Example: Structural Data***\n```matlab\ndcm{1}.folder = [cfg.rawDICOM filesep 't1_mprage*']; \ndcm{1}.dataType = 'anat';\ndcm{1}.modality = 'T1w';\n\ndcm{2}.folder = [cfg.rawDICOM filesep 't2_tse*']; \ndcm{2}.dataType = 'anat';\ndcm{2}.modality = 'T2w';\n```\nAs 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.\n\nEach 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`).\n\nA simple example for diffusion (DTI) data is shown below:\n\n***Example: Diffusion Data***\n```matlab\ndcm{3}.folder = [cfg.rawDICOM filesep 'ep2d_diff_mgh_1_39*'];\ndcm{3}.dataType = 'dwi';\ndcm{3}.modality = 'dwi';\n```\nDepending 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.\n\n***Example: Task-Based or Resting-State Functional Data***  \n```matlab\ndcm{4}.folder = [cfg.rawDICOM filesep 'task1*'];\ndcm{4}.dataType = 'func';\ndcm{4}.modality = 'bold';\ndcm{4}.task = 'task-task1';\ndcm{4}.events = 'events.tsv';\n\ndcm{5}.folder = [cfg.rawDICOM filesep 'task2*'];\ndcm{5}.dataType = 'func';\ndcm{5}.modality = 'bold';\ndcm{5}.task = 'task-task2';\ndcm{5}.events = 'events.tsv';\n\ndcm{6}.folder = [cfg.rawDICOM filesep 'task3*'];\ndcm{6}.dataType = 'func';\ndcm{6}.modality = 'bold';\ndcm{6}.task = 'task-task3';\ndcm{6}.events = 'events.tsv';\n```\nIn 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.\n\nThe field `dcm{x}.events` must specify the name of the `.tsv` file containing the event information, in cases where task-based data are included.\n\n***Example: Functional Data with Multiple Runs***  \nFor functional protocols with multiple runs, the parameter `run` must be included in the configuration:\n```matlab\ndcm{4}.folder = [cfg.rawDICOM filesep 'gonogo_run1*'];\ndcm{4}.dataType = 'func';   \ndcm{4}.modality = 'bold'; \ndcm{4}.task = 'task-gonogo';\ndcm{4}.run = 'run-1'; \ndcm{4}.events = 'events.tsv';\n\ndcm{5}.folder = [cfg.rawDICOM filesep 'gonogo_run2*'];\ndcm{5}.dataType = 'func';   \ndcm{5}.modality = 'bold'; \ndcm{5}.task = 'task-gonogo';\ndcm{5}.run = 'run-2';\ndcm{5}.events = 'events.tsv';\n\ndcm{6}.folder = [cfg.rawDICOM filesep 'gonogo_run3*'];\ndcm{6}.dataType = 'func';   \ndcm{6}.modality = 'bold'; \ndcm{6}.task = 'task-gonogo';\ndcm{6}.run = 'run-3';\ndcm{6}.events = 'events.tsv';\n```\n\n***Example: Field Map Data***  \nIn 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:\n```matlab\ndcm{7}.folder = [cfg.rawDICOM filesep 'gre_field_mapping_*'];\ndcm{7}.dataType = 'fmap';\ndcm{7}.modality = 'fieldmap';\n```\n\n## 3. Execution\n\nOnce 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.\n\n***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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcimcyc%2Fbids-converter-mri-matlab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcimcyc%2Fbids-converter-mri-matlab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcimcyc%2Fbids-converter-mri-matlab/lists"}