Batch-heudiconv: A Set of Utilities to Streamline DICOM to BIDS Conversion Using heudiconv
Poster No:
1849
Submission Type:
Abstract Submission
Authors:
Kiyotaka Nemoto1, Teruki Kuroshita2, Koichi Honda2, Kenjiro Nakayama1, Yuta Nakahashi1, Tetsuaki Arai1
Institutions:
1University of Tsukuba, Tsukuba, Ibaraki, 2University of Tsukuba Hospital, Tsukuba, Ibaraki
First Author:
Co-Author(s):
Introduction:
The Brain Imaging Data Structure (BIDS) has become the de facto standard for organizing neuroimaging data. While heudiconv is a powerful tool for converting DICOM files to BIDS format, its implementation requires complex command-line operations, including proper DICOM path configuration and preparation of heuristic files. These requirements often create barriers for researchers new to BIDS conversion, potentially limiting its adoption. Additionally, the creation of heuristic files, which define the mapping between DICOM series and BIDS entities, requires extensive knowledge of both the DICOM structure and BIDS specifications.
Methods:
We developed batch-heudiconv, a set of command-line utilities designed to simplify the DICOM to BIDS conversion workflow. The toolkit consists of five main scripts: (1) directory structure preparation following BIDS conventions, (2) DICOM sorting based on series description, (3) subject list generation supporting flexible naming patterns (e.g., {subject}_{session}), (4) automated heuristic file generation through series description analysis, and (5) BIDS conversion execution with proper error handling. The automated heuristic generation system implements sophisticated pattern matching for common MRI sequences, including T1w, T2w, functional MRI (with automatic detection based on number of volumes), diffusion-weighted imaging (with gradient direction detection), and various types of fieldmaps (both Siemens and GE formats). The system also incorporates special handling for double-echo fieldmaps, a common source of conversion errors. All scripts are written in bash with comprehensive error checking and user feedback, ensuring compatibility across Unix-like operating systems and robust execution.
·Workflow of batch-heudiconv
Results:
The implementation revealed several key findings that significantly improve the BIDS conversion workflow. First, normalizing DICOM paths through preliminary sorting proved essential for reliable conversion, as it standardizes the directory structure and eliminates naming inconsistencies. The sorting script successfully handles various naming conventions, focusing on the meaningful parts of series descriptions. Second, our automated heuristic generation system successfully creates customized heuristic.py files by analyzing series descriptions, with support for both session-based and simple subject-only directory structures. The system achieved high accuracy in detecting sequence types across different scanner manufacturers, particularly excelling at distinguishing between similar sequence types based on acquisition parameters. Third, the flexible subject list generation system effectively handles complex naming patterns, including cases where subject IDs contain multiple underscore characters. The toolkit includes comprehensive error checking and validation at each step, preventing common conversion failures. All components are freely available on GitHub (https://github.com/kytk/batch-heudiconv) and have been extensively tested with various neuroimaging datasets.
Conclusions:
batch-heudiconv significantly simplifies the DICOM to BIDS conversion process by providing an intuitive workflow and automated tools for common tasks. The toolkit's handling of series descriptions and flexible naming patterns makes it particularly valuable for research groups working with diverse imaging protocols. By automating the creation of heuristic files and standardizing directory structures, it lowers the technical barriers for researchers adopting BIDS, potentially accelerating the standardization of neuroimaging data organization. Future work will focus on expanding vendor support and adding support for more specialized imaging sequences. The toolkit's modular design allows for easy extension and customization, making it adaptable to various research workflows and requirements.
Neuroinformatics and Data Sharing:
Workflows 1
Informatics Other 2
Keywords:
Workflows
Other - BIDS
1|2Indicates the priority used for review