dicom2nii#

qx_utilities.dicom.legacy.dicom2nii.dicom2nii(folder='.', clean='no', unzip='yes', gzip='folder', verbose=True, parelements=1, debug=False)#

dicom2nii [folder=.] [clean=no] [unzip=ask] [gzip=folder] [verbose=True] [parelements=1]

Process sessions's DICOM or PAR/REC files and generate NIfTI files using dcm2niix.

Parameters

--folder (str, default '.'):: The base session folder with the dicom subfolder that holds session numbered folders with dicom files.
--clean (str, default 'no'):: Whether to remove preexisting NIfTI files ('yes'), leave them and abort ('no').
--unzip (str, default 'yes'):: If the dicom files are gziped whether to unzip them ('yes'), leave them be and abort ('no').
--gzip (str, default 'folder'):: Whether to gzip individual DICOM files after they were processed ('file'), gzip a DICOM sequence or acquisition as an tar.gz archive ('folder'), or leave them ungzipped ('no'). Valid options are 'folder', 'file', 'no'.
--verbose (bool, default True):: Whether to report on the progress (True) or not (False).
--parelements (int | str, default 1):: How many parallel processes to run dcm2nii conversion with. The number is 1 by default, if specified as 'all', all available resources are utilized.

Output files

After running, the command will place all the generated NIfTI files into the nii subfolder, named with sequential image number. It will also generate two additional files: a session.txt file and a DICOM-Report.txt file.

session.txt file:

The session.txt will be placed in the session base folder. It will contain the information about the session id, subject id, location of folders and a list of created NIfTI images with their description.

An example session.txt file would be:

id: OP169
subject: OP169
dicom: /Volumes/pooh/MBLab/fMRI/SWM-D-v1/sessions/OP169/dicom
raw_data: /Volumes/pooh/MBLab/fMRI/SWM-D-v1/sessions/OP169/nii
data: /Volumes/pooh/MBLab/fMRI/SWM-D-v1/sessions/OP169/4dfp
hcp: /Volumes/pooh/MBLab/fMRI/SWM-D-v1/sessions/OP169/hcp
Survey
T1w 0.7mm N1
T2w 0.7mm N1
Survey
C-BOLD 3mm 48 2.5s FS-P
C-BOLD 3mm 48 2.5s FS-A
BOLD 3mm 48 2.5s
BOLD 3mm 48 2.5s
BOLD 3mm 48 2.5s
BOLD 3mm 48 2.5s
BOLD 3mm 48 2.5s
BOLD 3mm 48 2.5s
RSBOLD 3mm 48 2.5s
RSBOLD 3mm 48 2.5s

For each of the listed images there will be a corresponding NIfTI file in the nii subfolder (e.g. 7.nii.gz for the first BOLD sequence), if a NIfTI file could be generated (Survey images for instance don't convert). The generated session.txt files form the basis for the following HCP and other processing steps.

DICOM-Report.txt file:

The DICOM-Report.txt file will be created and placed in the sessions' dicom subfolder. The file will list the images it found, the information about their original sequence number and the resulting NIfTI file number, the name of the sequence, the number of frames, TR and TE values, subject id, time of acquisition, information and warnings about any additional processing it had to perform (e.g. recenter structural images, switch f and z dimensions, reslice due to premature end of recording, etc.). In some cases some of the information (number of frames, TE, TR) might not be reported if that information was not present or couldn't be found in the DICOM file.

dcm2nii log files:

For each image conversion attempt a dcm2nii_[N].log file will be created that holds the output of the dcm2nii command that was run to convert the DICOM files to a NIfTI image.

Notes

The command is used to convert MR images from DICOM to NIfTI format. It searches for images within the dicom subfolder within the provided session folder (folder). It expects to find each image within a separate subfolder. It then converts the images to NIfTI format and places them in the nii folder within the session folder. To reduce the space use it can then gzip the dicom files (gzip). To speed the process up, it can run multiple dcm2nii processes in parallel (parelements).

Before running, the command check for presence of existing NIfTI files. The behavior when finding them is defined by clean parameter. If set to 'yes' it will remove any existing files and proceed. If set to 'no' it will leave them and abort.

Before running, the command also checks whether DICOM files might be gzipped. If that is the case, the response depends on the setting of the unzip parameter. If set to 'yes' it will automatically gunzip them and continue. If set to 'no', it will leave them be and abort.

Multiple sessions and scheduling:

The command can be run for multiple sessions by specifying sessions and optionally sessionsfolder and parelements parameters. In this case the command will be run for each of the specified sessions in the sessionsfolder (current directory by default). sessions limits the run to the specified id codes, and an optional filter parameter selects the sessions whose batch file entry matches a key. (for more information see online documentation). sessionsfolder will be filled in automatically as each sessions's folder. Commands will run in parallel by utilizing the specified number of parelements (1 by default).

If scheduler parameter is set, the command will be run using the specified scheduler settings (see qunex schedule --help for more information). If set in combination with sessions parameter, sessions will be processed over multiple nodes, core parameter specifying how many sessions to run per node. Optional scheduler_environment, scheduler_workdir, scheduler_sleep, and nprocess parameters can be set.

Set optional logfolder parameter to specify where the processing logs should be stored. Otherwise the processor will make best guess, where the logs should go.

Examples

qunex dicom2nii \
    --folder=. \
    --clean=yes \
    --unzip=yes \
    --gzip=folder \
    --parelements=3

Multiple sessions example:

qunex dicom2nii \
    --sessionsfolder="/data/my_study/sessions" \
    --sessions="OP*" \
    --clean=yes \
    --unzip=yes \
    --gzip=no \
    --parelements=3

QuNex documentation

dicom2nii

dicom2nii#