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)
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%
  |                                                                       
  |=====                                                            |   7%
  |                                                                       
  |=====                                                            |   8%
  |                                                                       
  |======                                                           |   9%
  |                                                                       
  |======                                                           |  10%
  |                                                                       
  |=======                                                          |  10%
  |                                                                       
  |=======                                                          |  11%
  |                                                                       
  |========                                                         |  12%
  |                                                                       
  |========                                                         |  13%
  |                                                                       
  |=========                                                        |  13%
  |                                                                       
  |=========                                                        |  14%
  |                                                                       
  |=========                                                        |  15%
  |                                                                       
  |==========                                                       |  15%
  |                                                                       
  |==========                                                       |  16%
  |                                                                       
  |===========                                                      |  16%
  |                                                                       
  |===========                                                      |  17%
  |                                                                       
  |===========                                                      |  18%
  |                                                                       
  |============                                                     |  18%
  |                                                                       
  |============                                                     |  19%
  |                                                                       
  |=============                                                    |  19%
  |                                                                       
  |=============                                                    |  20%
  |                                                                       
  |=============                                                    |  21%
  |                                                                       
  |==============                                                   |  21%
  |                                                                       
  |==============                                                   |  22%
  |                                                                       
  |===============                                                  |  22%
  |                                                                       
  |===============                                                  |  23%
  |                                                                       
  |===============                                                  |  24%
  |                                                                       
  |================                                                 |  24%
  |                                                                       
  |================                                                 |  25%
  |                                                                       
  |=================                                                |  26%
  |                                                                       
  |=================                                                |  27%
  |                                                                       
  |==================                                               |  27%
  |                                                                       
  |==================                                               |  28%
  |                                                                       
  |===================                                              |  28%
  |                                                                       
  |===================                                              |  29%
  |                                                                       
  |===================                                              |  30%
  |                                                                       
  |====================                                             |  30%
  |                                                                       
  |====================                                             |  31%
  |                                                                       
  |=====================                                            |  32%
  |                                                                       
  |=====================                                            |  33%
  |                                                                       
  |======================                                           |  33%
  |                                                                       
  |======================                                           |  34%
  |                                                                       
  |=======================                                          |  35%
  |                                                                       
  |=======================                                          |  36%
  |                                                                       
  |========================                                         |  36%
  |                                                                       
  |========================                                         |  37%
  |                                                                       
  |========================                                         |  38%
  |                                                                       
  |=========================                                        |  38%
  |                                                                       
  |=========================                                        |  39%
  |                                                                       
  |==========================                                       |  39%
  |                                                                       
  |==========================                                       |  40%
  |                                                                       
  |==========================                                       |  41%
  |                                                                       
  |===========================                                      |  41%
  |                                                                       
  |===========================                                      |  42%
  |                                                                       
  |============================                                     |  42%
  |                                                                       
  |============================                                     |  43%
  |                                                                       
  |============================                                     |  44%
  |                                                                       
  |=============================                                    |  44%
  |                                                                       
  |=============================                                    |  45%
  |                                                                       
  |==============================                                   |  45%
  |                                                                       
  |==============================                                   |  46%
  |                                                                       
  |==============================                                   |  47%
  |                                                                       
  |===============================                                  |  47%
  |                                                                       
  |===============================                                  |  48%
  |                                                                       
  |================================                                 |  49%
  |                                                                       
  |================================                                 |  50%
  |                                                                       
  |=================================                                |  50%
  |                                                                       
  |=================================                                |  51%
  |                                                                       
  |=================================                                |  52%
  |                                                                       
  |==================================                               |  52%
  |                                                                       
  |==================================                               |  53%
  |                                                                       
  |===================================                              |  53%
  |                                                                       
  |===================================                              |  54%
  |                                                                       
  |===================================                              |  55%
  |                                                                       
  |====================================                             |  55%
  |                                                                       
  |====================================                             |  56%
  |                                                                       
  |=====================================                            |  56%
  |                                                                       
  |=====================================                            |  57%
  |                                                                       
  |=====================================                            |  58%
  |                                                                       
  |======================================                           |  58%
  |                                                                       
  |======================================                           |  59%
  |                                                                       
  |=======================================                          |  59%
  |                                                                       
  |=======================================                          |  60%
  |                                                                       
  |=======================================                          |  61%
  |                                                                       
  |========================================                         |  61%
  |                                                                       
  |========================================                         |  62%
  |                                                                       
  |=========================================                        |  62%
  |                                                                       
  |=========================================                        |  63%
  |                                                                       
  |=========================================                        |  64%
  |                                                                       
  |==========================================                       |  64%
  |                                                                       
  |==========================================                       |  65%
  |                                                                       
  |===========================================                      |  65%
  |                                                                       
  |===========================================                      |  66%
  |                                                                       
  |===========================================                      |  67%
  |                                                                       
  |============================================                     |  67%
  |                                                                       
  |============================================                     |  68%
  |                                                                       
  |=============================================                    |  69%
  |                                                                       
  |=============================================                    |  70%
  |                                                                       
  |==============================================                   |  70%
  |                                                                       
  |==============================================                   |  71%
  |                                                                       
  |===============================================                  |  72%
  |                                                                       
  |===============================================                  |  73%
  |                                                                       
  |================================================                 |  73%
  |                                                                       
  |================================================                 |  74%
  |                                                                       
  |================================================                 |  75%
  |                                                                       
  |=================================================                |  75%
  |                                                                       
  |=================================================                |  76%
  |                                                                       
  |==================================================               |  76%
  |                                                                       
  |==================================================               |  77%
  |                                                                       
  |==================================================               |  78%
  |                                                                       
  |===================================================              |  78%
  |                                                                       
  |===================================================              |  79%
  |                                                                       
  |====================================================             |  79%
  |                                                                       
  |====================================================             |  80%
  |                                                                       
  |====================================================             |  81%
  |                                                                       
  |=====================================================            |  81%
  |                                                                       
  |=====================================================            |  82%
  |                                                                       
  |======================================================           |  82%
  |                                                                       
  |======================================================           |  83%
  |                                                                       
  |======================================================           |  84%
  |                                                                       
  |=======================================================          |  84%
  |                                                                       
  |=======================================================          |  85%
  |                                                                       
  |========================================================         |  85%
  |                                                                       
  |========================================================         |  86%
  |                                                                       
  |========================================================         |  87%
  |                                                                       
  |=========================================================        |  87%
  |                                                                       
  |=========================================================        |  88%
  |                                                                       
  |==========================================================       |  88%
  |                                                                       
  |==========================================================       |  89%
  |                                                                       
  |==========================================================       |  90%
  |                                                                       
  |===========================================================      |  90%
  |                                                                       
  |===========================================================      |  91%
  |                                                                       
  |============================================================     |  92%
  |                                                                       
  |============================================================     |  93%
  |                                                                       
  |=============================================================    |  93%
  |                                                                       
  |=============================================================    |  94%
  |                                                                       
  |==============================================================   |  95%
  |                                                                       
  |==============================================================   |  96%
  |                                                                       
  |===============================================================  |  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/bb/n7t3rs157850byt_jfdcq9k80000gn/T/RtmpW2yfnq/Rinst207e34c26a65/dcm2niir/dcm2niix' -z y -f %p_%t_%s '/var/folders/bb/n7t3rs157850byt_jfdcq9k80000gn/T//RtmpFTy3t1/file208a1708cdae'

res

## $result
## [1] 0
## 
## $nii_before
## character(0)
## 
## $nii_after
## [1] "/var/folders/bb/n7t3rs157850byt_jfdcq9k80000gn/T//RtmpFTy3t1/file208a1708cdae/T1w_TSE_pre_20150410095937_12.nii.gz"
## 
## $cmd
## [1] "'/private/var/folders/bb/n7t3rs157850byt_jfdcq9k80000gn/T/RtmpW2yfnq/Rinst207e34c26a65/dcm2niir/dcm2niix' -z y -f %p_%t_%s '/var/folders/bb/n7t3rs157850byt_jfdcq9k80000gn/T//RtmpFTy3t1/file208a1708cdae'"

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

## [1] "/var/folders/bb/n7t3rs157850byt_jfdcq9k80000gn/T//RtmpFTy3t1/file208a1708cdae/T1w_TSE_pre_20150410095937_12.nii.gz"

file.exists(checked)

## [1] TRUE

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

2017-12-05

Download the data

Loading the package

Convert the data

Manipulating the output