The dcm2niir package creates simple wrapper for the ‘dcm2nii’ and ‘dcm2niix’ functions from Chris Rorden (https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage) for converting Digital Imaging and Communications in Medicine (DICOM) data to Neuroimaging Informatics Technology Initiative (NIfTI) formats.

Download the data

For use in this vignette, we will download some mouse enhanced magnetic resonance image (MRI). In the case below, we are downloading a T1-weighted pre-contrast image. The dcm2niix software can handle individual DICOM images (1 dcm file per slice) or combined/3D DICOM images (1 dcm per volume). Below, the example dcm is an entire series/volume.

We will create a temporary directory and download the dcm file to that directory. We do this because dcm2niir::dcm2nii takes in a folder/directory as the main argument basedir.

library(utils)
# dcm_file = "ftp://medical.nema.org/medical/Dicom/DataSets/WG30/MGH/MR/MouseBrainSiemens15T_20150410/Converted/DICOM/mghmousetoenhancedmr_T1w_pre.dcm"
dcm_file = "http://johnmuschelli.com/dcm2niir/mghmousetoenhancedmr_T1w_pre.dcm"
tdir = tempfile()
dir.create(tdir)
destfile = tempfile(fileext = ".dcm", tmpdir = tdir)
ci = Sys.getenv("CI")
method = ifelse(ci == "", "auto", "curl")
dl = download.file(url = dcm_file, method = method, 
                   destfile = destfile, mode = "wb")
dl == 0

## [1] TRUE

file.exists(destfile)

## [1] TRUE

We see a zero exit status and that the data exists. If this fails, you may not have ftp capabilities with R or your internet connection. Otherwise, this data may have moved, and please email the maintainer or submit an issue/bug report.

Loading the package

We load the library here and run the install_dcm2nii function. This downloads the binaries of the dcm2nii and dcm2niix software to use at the command line. This only needs to be run once after the installation of dcm2niir. Most functions should check this before running, so this step is not completely necessary, but allows you to check if dcm2niix is installed, and if not, it will install the binary.

library(dcm2niir)
install_dcm2nii()

## 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |======================================================================| 100%
## 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |                                                                      |   1%
  |                                                                            
  |=                                                                     |   1%
  |                                                                            
  |=                                                                     |   2%
  |                                                                            
  |==                                                                    |   2%
  |                                                                            
  |==                                                                    |   3%
  |                                                                            
  |==                                                                    |   4%
  |                                                                            
  |===                                                                   |   4%
  |                                                                            
  |===                                                                   |   5%
  |                                                                            
  |====                                                                  |   5%
  |                                                                            
  |====                                                                  |   6%
  |                                                                            
  |=====                                                                 |   7%
  |                                                                            
  |=====                                                                 |   8%
  |                                                                            
  |======                                                                |   8%
  |                                                                            
  |======                                                                |   9%
  |                                                                            
  |=======                                                               |   9%
  |                                                                            
  |=======                                                               |  10%
  |                                                                            
  |=======                                                               |  11%
  |                                                                            
  |========                                                              |  11%
  |                                                                            
  |========                                                              |  12%
  |                                                                            
  |=========                                                             |  12%
  |                                                                            
  |=========                                                             |  13%
  |                                                                            
  |=========                                                             |  14%
  |                                                                            
  |==========                                                            |  14%
  |                                                                            
  |==========                                                            |  15%
  |                                                                            
  |===========                                                           |  15%
  |                                                                            
  |===========                                                           |  16%
  |                                                                            
  |============                                                          |  17%
  |                                                                            
  |============                                                          |  18%
  |                                                                            
  |=============                                                         |  18%
  |                                                                            
  |=============                                                         |  19%
  |                                                                            
  |==============                                                        |  19%
  |                                                                            
  |==============                                                        |  20%
  |                                                                            
  |==============                                                        |  21%
  |                                                                            
  |===============                                                       |  21%
  |                                                                            
  |===============                                                       |  22%
  |                                                                            
  |================                                                      |  22%
  |                                                                            
  |================                                                      |  23%
  |                                                                            
  |================                                                      |  24%
  |                                                                            
  |=================                                                     |  24%
  |                                                                            
  |=================                                                     |  25%
  |                                                                            
  |==================                                                    |  25%
  |                                                                            
  |==================                                                    |  26%
  |                                                                            
  |===================                                                   |  26%
  |                                                                            
  |===================                                                   |  27%
  |                                                                            
  |===================                                                   |  28%
  |                                                                            
  |====================                                                  |  28%
  |                                                                            
  |====================                                                  |  29%
  |                                                                            
  |=====================                                                 |  29%
  |                                                                            
  |=====================                                                 |  30%
  |                                                                            
  |=====================                                                 |  31%
  |                                                                            
  |======================                                                |  31%
  |                                                                            
  |======================                                                |  32%
  |                                                                            
  |=======================                                               |  32%
  |                                                                            
  |=======================                                               |  33%
  |                                                                            
  |========================                                              |  34%
  |                                                                            
  |========================                                              |  35%
  |                                                                            
  |=========================                                             |  35%
  |                                                                            
  |=========================                                             |  36%
  |                                                                            
  |==========================                                            |  36%
  |                                                                            
  |==========================                                            |  37%
  |                                                                            
  |==========================                                            |  38%
  |                                                                            
  |===========================                                           |  38%
  |                                                                            
  |===========================                                           |  39%
  |                                                                            
  |============================                                          |  39%
  |                                                                            
  |============================                                          |  40%
  |                                                                            
  |============================                                          |  41%
  |                                                                            
  |=============================                                         |  41%
  |                                                                            
  |=============================                                         |  42%
  |                                                                            
  |==============================                                        |  42%
  |                                                                            
  |==============================                                        |  43%
  |                                                                            
  |==============================                                        |  44%
  |                                                                            
  |===============================                                       |  44%
  |                                                                            
  |===============================                                       |  45%
  |                                                                            
  |================================                                      |  45%
  |                                                                            
  |================================                                      |  46%
  |                                                                            
  |=================================                                     |  47%
  |                                                                            
  |=================================                                     |  48%
  |                                                                            
  |==================================                                    |  48%
  |                                                                            
  |==================================                                    |  49%
  |                                                                            
  |===================================                                   |  49%
  |                                                                            
  |===================================                                   |  50%
  |                                                                            
  |===================================                                   |  51%
  |                                                                            
  |====================================                                  |  51%
  |                                                                            
  |====================================                                  |  52%
  |                                                                            
  |=====================================                                 |  52%
  |                                                                            
  |=====================================                                 |  53%
  |                                                                            
  |=====================================                                 |  54%
  |                                                                            
  |======================================                                |  54%
  |                                                                            
  |======================================                                |  55%
  |                                                                            
  |=======================================                               |  55%
  |                                                                            
  |=======================================                               |  56%
  |                                                                            
  |========================================                              |  57%
  |                                                                            
  |========================================                              |  58%
  |                                                                            
  |=========================================                             |  58%
  |                                                                            
  |=========================================                             |  59%
  |                                                                            
  |==========================================                            |  59%
  |                                                                            
  |==========================================                            |  60%
  |                                                                            
  |==========================================                            |  61%
  |                                                                            
  |===========================================                           |  61%
  |                                                                            
  |===========================================                           |  62%
  |                                                                            
  |============================================                          |  62%
  |                                                                            
  |============================================                          |  63%
  |                                                                            
  |============================================                          |  64%
  |                                                                            
  |=============================================                         |  64%
  |                                                                            
  |=============================================                         |  65%
  |                                                                            
  |==============================================                        |  65%
  |                                                                            
  |==============================================                        |  66%
  |                                                                            
  |===============================================                       |  66%
  |                                                                            
  |===============================================                       |  67%
  |                                                                            
  |===============================================                       |  68%
  |                                                                            
  |================================================                      |  68%
  |                                                                            
  |================================================                      |  69%
  |                                                                            
  |=================================================                     |  69%
  |                                                                            
  |=================================================                     |  70%
  |                                                                            
  |=================================================                     |  71%
  |                                                                            
  |==================================================                    |  71%
  |                                                                            
  |==================================================                    |  72%
  |                                                                            
  |===================================================                   |  72%
  |                                                                            
  |===================================================                   |  73%
  |                                                                            
  |====================================================                  |  74%
  |                                                                            
  |====================================================                  |  75%
  |                                                                            
  |=====================================================                 |  75%
  |                                                                            
  |=====================================================                 |  76%
  |                                                                            
  |======================================================                |  76%
  |                                                                            
  |======================================================                |  77%
  |                                                                            
  |======================================================                |  78%
  |                                                                            
  |=======================================================               |  78%
  |                                                                            
  |=======================================================               |  79%
  |                                                                            
  |========================================================              |  79%
  |                                                                            
  |========================================================              |  80%
  |                                                                            
  |========================================================              |  81%
  |                                                                            
  |=========================================================             |  81%
  |                                                                            
  |=========================================================             |  82%
  |                                                                            
  |==========================================================            |  82%
  |                                                                            
  |==========================================================            |  83%
  |                                                                            
  |==========================================================            |  84%
  |                                                                            
  |===========================================================           |  84%
  |                                                                            
  |===========================================================           |  85%
  |                                                                            
  |============================================================          |  85%
  |                                                                            
  |============================================================          |  86%
  |                                                                            
  |=============================================================         |  87%
  |                                                                            
  |=============================================================         |  88%
  |                                                                            
  |==============================================================        |  88%
  |                                                                            
  |==============================================================        |  89%
  |                                                                            
  |===============================================================       |  89%
  |                                                                            
  |===============================================================       |  90%
  |                                                                            
  |===============================================================       |  91%
  |                                                                            
  |================================================================      |  91%
  |                                                                            
  |================================================================      |  92%
  |                                                                            
  |=================================================================     |  92%
  |                                                                            
  |=================================================================     |  93%
  |                                                                            
  |=================================================================     |  94%
  |                                                                            
  |==================================================================    |  94%
  |                                                                            
  |==================================================================    |  95%
  |                                                                            
  |===================================================================   |  95%
  |                                                                            
  |===================================================================   |  96%
  |                                                                            
  |====================================================================  |  97%
  |                                                                            
  |====================================================================  |  98%
  |                                                                            
  |===================================================================== |  98%
  |                                                                            
  |===================================================================== |  99%
  |                                                                            
  |======================================================================|  99%
  |                                                                            
  |======================================================================| 100%

## [1] TRUE

Convert the data

The main function is dcm2nii, and again the main argument is basedir. The argument copy_files indicates if the data from basedir should be copied to a temporary directory and dcm2nii will be run on that. This ensures nothing is done to the original data in case of a failure.

res = dcm2niir::dcm2nii(basedir = tdir)

## #Copying Files

## # Converting to nii

## '/private/var/folders/nz/vv4_9tw56nv9k3tkvyszvwg80000gn/T/Rtmpv0ylz5/Rinst1459e671382a9/dcm2niir/dcm2niix' -9  -v 1 -z y -f %p_%t_%s '/var/folders/nz/vv4_9tw56nv9k3tkvyszvwg80000gn/T/RtmpX4uCBN/file145b03c954503'

## Warning in dcm2niir::dcm2nii(basedir = tdir): Result indicated an error! Please
## check results.

res

## $result
## [1] 2
## 
## $nii_before
## character(0)
## 
## $nii_after
## character(0)
## 
## $json_after
## character(0)
## 
## $json_before
## character(0)
## 
## $cmd
## [1] "'/private/var/folders/nz/vv4_9tw56nv9k3tkvyszvwg80000gn/T/Rtmpv0ylz5/Rinst1459e671382a9/dcm2niir/dcm2niix' -9  -v 1 -z y -f %p_%t_%s '/var/folders/nz/vv4_9tw56nv9k3tkvyszvwg80000gn/T/RtmpX4uCBN/file145b03c954503'"

The command line results from dcm2niix should be printed out along with the command.

We see the resulting list consisting of the result (exit status of dcm2niix - 0 means success), nii_before (filenames of NIfTI files in the directory before running), nii_after (filenames of NIfTI files in the directory before running, these are the converted ones), and the command passed to system (in the cmd slot).

Manipulating the output

There is a quick wrapper function called check_dcm2nii that takes this output. If there are multiple outputs for the same sequence, which may happen with variable slice thicknesses in the sequence (CT or MRI), which is interpolated, or gantry tilt (CT), then check_dcm2nii will try to choose the correct one. Otherwise, it returns the nii_after element. Either way, it returns a character vector:

checked = check_dcm2nii(res)
checked

## character(0)
## attr(,"json_file")
## character(0)

file.exists(checked)

## logical(0)

Now this file can be read in using neurobase::readnii, ortho2::readNIfTI, RNifti::readNifti, or ANTsR::antsImageRead and be used as a 3D image.

Converting DICOMs to NIfTI Images

John Muschelli

2020-04-29

Download the data

Loading the package

Convert the data

Manipulating the output