Add a Dicom2BIDS tool

[xmpham]

Dicom to BIDS tool to be integrated into CBRAIN, dcm2bids is a community-centred project. It aims to be a friendly, easy-to-use tool to convert your dicoms. The goal is to make the dicom to BIDS conversion:
Please find the documentation below:

https://github.com/UNFmontreal/Dcm2Bids

https://unfmontreal.github.io/Dcm2Bids/3.2.0/#major-upgrade-with-dcm2bids-300

[MontrealSergiy]

Mai, could you provide more details? E.g. clarify, is there a user or managerial request behind it? This information might help us better assess its priority and time frame for that toolbox integration and understand which use cases we should target.

[bryancaron]

During the meeting of October 31 with the MPN MRI taskforce team, a few different methods were discussed in regard to performing the dicom to bids conversion, but not one in particular was determined in that call to be the one method they would use, so as to handle all the particulars required (for example, some phases were not properly included after the bids-ification) . I indicated that from the CBRAIN perspective it would be ideal that once a final method / software package was chosen to do the dicom to bids conversion then we would use the same in CBRAIN.

We will see at the next meeting (November 14) if there is any convergence on the package to be used for the conversion.

Bryan.

[bryancaron]

Subsequent to the discussion at today's CBRAIN meeting, let's proceed with the configuration of the dcm2bids as a tool in CBRAIN.

If there are any questions regarding the design and/or implementation of the integration, please post here for follow-up and discussion.

Thanks!

Bryan.

[xmpham]

Following the meeting on November 14th, the team still has to decide which tool Dicom2Bids to use for the conversion.

• However, they confirmed that the script REQUIRES dcm2niix to work (code available on the following GitHub page)

  https://github.com/rordenlab/dcm2niix
  

• dcm2nii DICOM to NIfTI converter: compiled versions are available from NITRC Website
  (https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage

The final script (Dicom2Bids) will be provided by Raul

[MontrealSergiy]

There is a container image that includes both dcm2niix and dcm2bids as well as pydeface.

https://unfmontreal.github.io/Dcm2Bids/3.2.0/how-to/container/#step-5-run-dcm2bids

[MontrealSergiy]

Note, Dcm2Bids authors asks users to cite the tool whenever it is used in research.

I think we can create add a 'license' or 'warning' mechanisms similar to file access, which should work with public groups. Project license is still is not shown on cbrain side, just error message. Maybe fix or add a link to neurohub?

Another option add text to task, maybe as dummy mandatory argument ( I agree to refer 'dcm2bids' in my publications. - Yes )

If you use dcm2bids in your research or as part of your developments, please always cite the reference below.

APA
Boré, A., Guay, S., Bedetti, C., Meisler, S., & GuenTher, N. (2023). Dcm2Bids (Version 3.1.1) [Computer software]. https://doi.org/10.5281/zenodo.8436509

[MontrealSergiy]

Note that the standard apptainer image would not work on the outdated versions of the apptainer, installed on cluster such as 1.1 (beluga), 1.2.4 (grahem, cedar). More recent version of the apptainer 1.3.4+ as on ace-cbrain-1 or ace-cbrain-2.cbrain.mcgill.ca should work

[MontrealSergiy]

Not sure at the moment what output we aim for, a BIDS subject, a BIDS dataset, and perhaps some intermediate directories.

I guess eventually all will be needed, but will start for now with subject, then if intended user requests add intermediate directories.

[bryancaron]

FYI from a separate email discussion with V. Fonov of the project team and how they use dcm2niix. The version listed below is the latest. Note the use of the "ProtocolName" attribute.

`so, my version of dcm2niix :

dcm2niix -version
Chris Rorden's dcm2niiX version v1.0.20240202 GCC12.3.0 x86-64 (64-bit Linux)
v1.0.20240202

I installed from the conda-forge ( i.e conda install dcm2niix -c conda-forge) . In my conversion experiments, I first split all DICOM files into subdirectories, using the "ProtocolName" attribute using pydicom library. `

Bryan.

[MontrealSergiy]

presently dcm2bids 3.2.0 container contains exactly dcm2niiX version v1.0.20240202 . So, hopefully everything ok.

Note this ticket is devoted to dcm2bids deployments, should I add dcm2niiX, please advice or create an additional issue. I think CBRAIN currently offers a 10 year old ancestor of dcm2niiX called dcm2nii, yet some user can benefits from a more modern tool.

[prioux]

Don't fret about internal tools like dcm2niix. All we want is just dcm2bids exactly as provided by the devs. We just need a descriptor for it, and it should work just as intended, generating a BIDS dataset, not a BIDS subject. Write a descriptor and test it straight like that.

[bryancaron]

I agree fully Pierre.

[MontrealSergiy]

@prioux @bryancaron

A straightforward dcm2bids 'as provided by devs' Boutiques descriptors is ready and tested for DICOM-to-BIDS subject folder conversion. Regretfully, dcm2bids tool does not exactly provide conversion at the dataset level, which is the case with most DICOM-to-BIDS converters. Note the transformation is not fully automatic and relies on a manually written config file. Splitting of DICOM into participant folders is also done by user.

dcm2nii command, as provided by the developers, does not generate a BIDS dataset.
It only converts one single-subject DICOM folder into one BIDS subject folder.
However, users can place that one subject into a ‘BIDS’ scaffolding folder, typically previously generated with dcm2bids_scaffolding.

The situation might be explained by the fact that this writing json config is tricky, and should be achieved step by step.
User is supposed to achieve deep understand the structure, modalities and study protocol of the DICOM dataset. Typically users examine the output of dcm2nii or dcm2bids_helper for few typical participants and define the configuration. A minute change to dcm2niiX might make old configs failing.

Few other converters such as Clinica may reduce challenge by providing template library for configs for different study and analysis types (per disease/goal, and other metadata), so user just adjust a template or combines several. But I can imagine experienced users such as Vladimir might have they own collection of typical configs templates or examples.

More, it is up to the user to break up the original DICOM dataset into multiple single-subject folders.
For instance, Vladimir uses a Python library pydicom to accomplish this.

If all subjects contain similar data, it is enough to test and debug one config file.
To convert the rest of the subjects in one shot, the user has to write their own script.
The tutorial suggests using the GNU parallel utility to involve as many processors as available, rather than a bash loop.
Subject folders are named after subject IDs. The tutorial advocates the use of GNU parallel as some datasets can be quite large, and users are encouraged to invoke non-trivial, resource-consuming commands in the config file, such as pydeface.
Extending the Tool for Dataset-Level Conversion:

I can modify the tool to generate a whole dataset by:

• Using a bash wrapper with parallel.
• Using a bash wrapper with a loop.
• Using CBRAIN file lists.
• Using extended CBRAIN lists (so folder names could be different from subject IDs).

For now user will still have to restructure the DICOM dataset onto separate folders. Which latter can be delegated to separate DICOM2sub tool (tentatively to be written).

As defining a transformation configuration is an error-prone and complicated task, I see users reporting bugs even regarding the tutorial config. Therefore, it is still recommended to first try on one subject. I would present the current straightforward Boutiques setup, and if you like, I could submit a PR with it for review.