dicom2niix#

qx_utilities.dicom.dicom2niix.dicom2niix(folder='.', clean='no', unzip='yes', gzip='folder', sessionid=None, verbose=True, parelements=1, debug=False, tool='auto', add_image_type=0, add_json_info='', _log=None)#

dicom2niix [folder=.] [clean=no] [unzip=yes] [gzip=folder] [sessionid=None] [verbose=True] [parelements=1] [tool='auto'] [add_image_type=0] [add_json_info=""]

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'.

--sessionid (str, default ''):

The id code to use for this session. If not provided, the session id is extracted from dicom files.

--verbose (bool, default True):

Whether to report on the progress (True) or not (False).

--parelements (str, default '1'):

How many parallel processes to run dcm2nii conversion with. The number is one by defaults, if specified as 'all', all available resources are utilized.

--tool (str, default 'auto'):

What tool to use for the conversion. It can be one of:

'auto' (determine best tool based on heuristics)
'dcm2niix'
'dcm2nii'
'dicm2nii'.

--add_image_type (int, default 0):

Adds image type information to the sequence name (Siemens scanners). The value should specify how many of image type labels from the end of the image type list to add.

--add_json_info (str, default 'all'):

What sequence information to extract from JSON sidecar files and add to session.txt file. Specify a comma separated list of fields or 'all'. See list in session.txt file description below.

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.

Subject id will be extracted from the session id assuming the session id formula: <subject id>_<session id>. If there is no underscore in the session id, the subject id is assumed to equal session id.

An example session.txt file would be:

id: OP169_baseline
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.

The following information can be extracted from sidecar JSON files and added to the sequence information in session.txt file:

:<fieldname>:       <JSON key>
:TR:                RepetitionTime
:PEDirection:       PhaseEncodingDirection
:EchoSpacing:       EffectiveEchoSpacing
:DwellTime:         DwellTime
:ReadoutDirection:  ReadoutDirection

DICOM-Report.txt file:

The DICOM-Report.txt file will be created and placed in the session's 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, session 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.

log files:

For each image conversion attempt a dcm2nii_[N] (or dicm2nii_[N].log) file will be created that holds the output of the command that was run to convert the DICOM or PAR/REC files to a NIfTI image.

Notes

The command is used to convert MR images from DICOM and PAR/REC files to NIfTI format. It searches for images within the a dicom subfolder within the provided session folder (folder). It expects to find each image within a separate subfolder. It then converts the found images to NIfTI format and places them in the nii folder within the session folder. To reduce the space used it can then gzip the dicom or .REC files (gzip). The tool to be used for the conversion can be specified explicitly or determined automatically. It can be one of 'dcm2niix', 'dcm2nii', 'dicm2nii' or 'auto'. If set to 'auto', for dicom files the conversion is done using dcm2niix, and for PAR/REC files, dicm2nii is used if QuNex is set to use Matlab, otherwise also PAR/REC files are converted using dcm2niix. If set explicitly, the command will try to use the tool specified. To speed the process up, the command can run it can run multiple conversion processes in parallel. The number of processes to run in parallel is specified using the parelements parameter.

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 proceede. If set to 'no' it will leave them and abort.

Before running, the command also checks whether DICOM or .REC 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). sfolder 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 dicom2niix \
    --folder=. \
    --clean=yes \
    --unzip=yes \
    --gzip=folder \
    --parelements=3

Multiple sessions example:

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

QuNex documentation

dicom2niix

dicom2niix#