readDicom {divest}

Read one or more DICOM directories

Description

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.

Usage

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

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

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

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.

output

The directory to write converted or copied NIfTI files to, or NULL. In the latter case, which isn't valid for sortDicom, images are converted in memory and returned as R objects.

nested

For sortDicom, should the sorted files be created within the source directory (TRUE), or in the current working directory (FALSE)? Now soft-deprecated in favour of output, which is more flexible.

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.

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). convertDicom performs the same conversion but writes to NIfTI files by default, instead of retaining the images in memory. 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.

Value

readDicom and convertDicom return a list of niftiImage objects if output is NULL; otherwise a vector of paths to NIfTI-1 files created in the target directory. 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.

Author(s)

Jon Clayden <[e-mail]>

Examples

path <- system.file("extdata", "raw", package="divest")
scanDicom(path)
readDicom(path, interactive=FALSE)