[RESOLVED] Naming of Dicom and nii files

I feel that my question is very basic but still could not find an answer.
While using QuNex container as in the quickstart guide using our lab MRI data, a folder is created for every session with “dicom” folder and “nii” folder in it. These folder contains files of the raw data with number as names, based on their sequential numbers in the original folder. Is there a way to name these files with more informative names (or with the original names)?

For example, a session with the following folders:

10_rfMRI_BJJ2_AP_SBRef 16_dMRI_MB4_185dirs_d15D45_AP_SBRef 21_T1w_MPRAGE_RL 7_T1w_MPRAGE_RL
11_rfMRI_BJJ2_AP 17_dMRI_MB4_185dirs_d15D45_AP 2_SpinEchoFieldMap_AP 8_T1w_MPRAGE_RL
12_rfMRI_Climbing2_AP_SBRef 18_dMRI_MB4_6dirs_d15D45_PA_SBRef 3_SpinEchoFieldMap_PA 9_T2w_SPC_RL
13_rfMRI_Climbing2_AP 19_dMRI_MB4_6dirs_d15D45_PA 4_rsfMRI_AP_SBRef
14_rfMRI_Music2_AP_SBRef ‘1_localizer_3D_2 (9X5X5)’ 5_rsfMRI_AP
15_rfMRI_Music2_AP 20_T1w_MPRAGE_RL 6_t2_tirm_tra_dark-fluid_FLAIR

the following dicom folder:

10.tar.gz 160.tar.gz 30.tar.gz DICOM-Report.txt dcm2niix_150.log dcm2niix_210.log dcm2niix_90.log
100.tar.gz 170.tar.gz 40.tar.gz dcm2niix_10.log dcm2niix_160.log dcm2niix_30.log
110.tar.gz 180.tar.gz 50.tar.gz dcm2niix_100.log dcm2niix_170.log dcm2niix_40.log
120.tar.gz 190.tar.gz 60.tar.gz dcm2niix_110.log dcm2niix_180.log dcm2niix_50.log
130.tar.gz 20.tar.gz 70.tar.gz dcm2niix_120.log dcm2niix_190.log dcm2niix_60.log
140.tar.gz 200.tar.gz 80.tar.gz dcm2niix_130.log dcm2niix_20.log dcm2niix_70.log
150.tar.gz 210.tar.gz 90.tar.gz dcm2niix_140.log dcm2niix_200.log dcm2niix_80.log

and the following nii folder:

101.json 111.nii.gz 13.json 141.nii.gz 171.bval 181.nii.gz 201.json 211.nii.gz 51.json 71.nii.gz
101.nii.gz 12.json 13.nii.gz 151.json 171.bvec 191.bval 201.nii.gz 31.json 51.nii.gz 81.json
11.json 12.nii.gz 131.json 151.nii.gz 171.json 191.bvec 21.json 31.nii.gz 61.json 81.nii.gz
11.nii.gz 121.json 131.nii.gz 161.json 171.nii.gz 191.json 21.nii.gz 41.json 61.nii.gz 91.json
111.json 121.nii.gz 141.json 161.nii.gz 181.json 191.nii.gz 211.json 41.nii.gz 71.json 91.nii.gz

Thank you in advance,

Hi Theo,

Welcome to the QuNex forums!

No, QuNex will store files as numbers. This organization is much easier for us to handle in the back. However, additional information is not discarded and can be used later on. All information is stored in the session file. For example, if my session name is P10 then its session file will be in <qunex_study>/sessions/P10/session.txt. So, QuNex stores all the info about images and uses it later on.

For example, when preparing to run HCP pipelines with the setup_hcp command, you can specify whether you want to have original names in the HCP folder strucutre or automated/numerical/QuNex ones. This is controlled through the --hcp_filename parameters. If this parameter is set to automated (default) then numbers will be used for naming files, e.g. BOLDs will be named BOLD_1, BOLD_2, etc. If userdefined is used then original filenames will be used, in your case rfMRI_Climbing2_AP, etc. Try running setup_hcp with both options for hcp_filename and then inspect the session’s hcp folder (e.g., <qunex_study>/sessions/P10/hcp`).

Based on your question, I would propose that you use --hcp_filename=userdefined option. Maybe best to just set this in the parameter/batch file and it will be automatically propagated to all relevant commands.

Hope my answer will help you.

Cheers, Jure

Thanks a lot for the quick and detailed response,
I will try it.

Actually, I think I maybe jumped the gun here. It could be that the described functionality is only provided when onboarding data through import_hcp. I need to double check this myself as well.

If this is the case, I will open a discussion about this internally and we will see if we can add this functionality when starting with import_dicom as well.


When I tried to run import_dicom instead of the whole run_turnkey process, I got the same folders and filenames of raw data. I didn’t add any special flag, though.

In any case, thank you again for your help.


Theo, hi!

Let me chime in. During import of DICOM data, the following occurs. First, dicom files are copied (or moved, depending on the setting) into <session id>/inbox folder. The dicom files in that folder are then inspected and moved into <session id>/dicom/<sequence number> folder. At this point, dicom files are also renamed to include session id, series number, and instance UID. This renaming is currently hardcoded and can not be changed without changing QuNex code. The reason for sorting dicom files in this manner is to ensure that (i) all dicom files from a single sequence are in a separate folder – this is done to facilitate conversion to nifti and to avoid any possible issues –, and (ii) that the sequences are ordered by their acquisition, which supports a number of features later on in processing (identifying which field-map goes with which structural and functional scan, optimization of fMRI processing).

Dicom files are then converted to nifti and mapped into <session id>/nii folder. To have a clear reference to dicom files and, again, to track their order of acquisition, the nifti files are also named sequentially using numbers. This behavior is also hardcoded into QuNex. Of note, the sequence names (as present in dicom data) are stored in the session.txt files for each participant, so that the files can then be easily tagged. An example would be:

110: RSBOLD 3mm 48 2.5s

In this example, the sequence name for the nifti file 110.nii.gz was RSBOLD 3mm 48 2.5s. This allows creation of session_hcp.txt file using the create_session_info command. Specifically, provided a mapping file with line:

RSBOLD 3mm 48 2.5s => bold:rest

a session_hcp.txt file will be created with a corresponding line:

110: bold1: rest: RSBOLD 3mm 48 2.5s

The mapping if flexible, so additional information can be provided. Relevant for your question would be the option to add a filename() parameter, e.g.:

RSBOLD 3mm 48 2.5s => bold:rest:filename(RSBOLD)

this will now result in a session_hcp.txt file with a corresponding line:

110: bold1: rest: RSBOLD 3mm 48 2.5s : filename(RSBOLD)

By default, when mapped for HCP minimal preprocessing, the bold files are named sequentially BOLD_1, BOLD_2, corresponding to the bold number in the session_hcp.txt file. However, if hcp_filename parameter is set to userdefined, the bold files will be named according to the filename information provided in the session_hcp.txt file. In the above example, instead of BOLD_1, the resting state run would be named RSBOLD within the HCP minimal processing pipeline. Please, do take into account that in this case the onus is on the user to ensure that bold files have unique filenames!

When the bold files are mapped back to the QuNex folder structure for further processing and analysis, they are renamed back to bold1, bold2. bold can be replaced by another prefix using the boldname parameter, however, the naming will be sequential.

I hope that this answers your question, and that I have not overwhelmed you with information.

All the best,


1 Like

That was very helpful,
Thank you