Read one or more DICOM directories

These functions are R wrappers around the DICOM-to-NIfTI conversion routines provided by dcm2niix. They scan directories containing DICOM files, potentially pertaining to more than one image series, read them and/or merge them into a list of niftiImage objects.

readDicom(path = ".", subset = NULL, flipY = TRUE, crop = FALSE,
  forceStack = FALSE, verbosity = 0L, labelFormat = "T%t_N%n_S%s",
  depth = 5L, interactive = base::interactive())

sortDicom(path = ".", forceStack = FALSE, verbosity = 0L,
  labelFormat = "T%t_N%n_S%s/%b", depth = 5L, nested = TRUE,
  keepUnsorted = FALSE)

scanDicom(path = ".", forceStack = FALSE, verbosity = 0L,
  labelFormat = "T%t_N%n_S%s", depth = 5L)

Arguments

path	A character vector of paths to scan for DICOM files. Each will examined in turn. The default is the current working directory. readDicom (only) will accept paths to individual DICOM files, rather than directories. Alternatively, for readDicom and sortDicom, a data frame like the one returned by scanDicom, from which file paths will be read.
subset	If path is a data frame, an expression which will be evaluated in the context of the data frame to determine which series to convert. Should evaluate to a logical vector. If path is a character vector, scanDicom is called on the path(s) first to produce the data frame. If this is specified, and does not evaluate to NULL, the read will be noninteractive, irrespective of the value of the interactive argument.
flipY	If TRUE, the default, then images will be flipped in the Y-axis. This is usually desirable, given the difference between orientation conventions in the DICOM and NIfTI-1 formats.
crop	If TRUE, then dcm2niix will attempt to crop excess neck slices from brain images.
forceStack	If TRUE, images with the same series number will always be stacked together as long as their dimensions are compatible. If FALSE, the default, images will be separated if they differ in echo, coil or exposure number, echo time, protocol name or orientation.
verbosity	Integer value between -2 and 3, controlling the amount of output generated during the conversion. A value of -1 will suppress all output from dcm2niix except warnings and errors; -2 also suppresses warnings.
labelFormat	A sprintf-style string specifying the format to use for the final image labels or paths. See Details.
depth	The maximum subdirectory depth in which to search for DICOM files, relative to each path.
interactive	If TRUE, the default in interactive sessions, the requested paths will first be scanned and a list of DICOM series will be presented. You may then choose which series to convert.
nested	For sortDicom, should the sorted files be created within the source directory (TRUE, the default), or in the current working directory (FALSE)?
keepUnsorted	For sortDicom, should the unsorted files be left in place, or removed after they are copied into their new locations? The default, FALSE, corresponds to a move rather than a copy. If creating new files fails then the old ones will not be deleted.

Value

The readDicom function returns a list of niftiImage objects, which can be easily converted to standard R arrays or written to NIfTI-1 format using functions from the RNifti package. The scanDicom function returns a data frame containing information about each DICOM series found. sortDicom is mostly called for its side-effect, but also (invisibly) returns a list detailing source and target paths.

Details

The scanDicom function parses directories full of DICOM files and returns information about the acquisition series they contain. readDicom reads these files and converts them to (internal) NIfTI images (whose pixel data can be extracted using as.array). sortDicom renames the files, but does not convert them.

The labelFormat argument describes the string format used for image labels and sorted files. Valid codes, each escaped with a percentage sign, include a for coil number, b for the source file base name, c for image comments, d for series description, e for echo number, f for the source directory, i for patient ID, j for the series instance UID, k for the study instance UID, l for the procedure step description, m for manufacturer, n for patient name, p for protocol name, q for scanning sequence, r for instance number, s for series number, t for the date and time, u for acquisition number, v for vendor, x for study ID and z for sequence name. For sortDicom the label forms the new file path, and may include one or more slashes to create subdirectories. A ".dcm" suffix will be added to file names if no extension is specified.

Author

Jon Clayden <code@clayden.org>

Examples

path <- system.file("extdata", "raw", package="divest")
scanDicom(path)
#> [dcm2niix info] Found 4 DICOM file(s)
#>     label                                           rootPath files seriesNumber
#> 2 T0_N_S8 /home/runner/work/_temp/Library/divest/extdata/raw     2            8
#> 1 T0_N_S9 /home/runner/work/_temp/Library/divest/extdata/raw     2            9
#>   seriesDescription patientName studyDate echoTime repetitionTime echoNumber
#> 2        DTIb3000s5        <NA>      <NA>   112.00           4100         NA
#> 1       fl3D_t1_sag        <NA>      <NA>     4.94             11         NA
#>   phase diffusion
#> 2 FALSE      TRUE
#> 1 FALSE     FALSE
readDicom(path, interactive=FALSE)
#> [dcm2niix info] Found 4 DICOM file(s)
#> [dcm2niix WARNING] Unable to determine manufacturer (0008,0070), so conversion is not tuned for vendor.
#> [dcm2niix WARNING] All images appear to be a single slice - please check slice/vector orientation
#> [dcm2niix info] Convert 2 DICOM as T0_N_S8 (96x96x1x2)
#> [dcm2niix WARNING] Check that 2D images are not mirrored.
#> [dcm2niix WARNING] Unable to determine manufacturer (0008,0070), so conversion is not tuned for vendor.
#> [dcm2niix info] Convert 2 DICOM as T0_N_S9 (224x256x2x1)
#> [[1]]
#> Internal image: "T0_N_S8"
#> - 96 x 96 x 1 x 2 voxels
#> - 2.5 x 2.5 x 5 mm x 4.1 s per voxel
#> 
#> [[2]]
#> Internal image: "T0_N_S9"
#> - 2 x 224 x 256 voxels
#> - 1 x 1 x 1 mm per voxel
#>