Comparison to metadata extraction with oro.dicom and oro.nifti

In radtools: Utilities for Convenient Extraction of Medical Image Metadata

rm(list=ls())
suppressPackageStartupMessages(library(knitr))
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE
)

# Check if this is running locally and if not, suppress evaluation
if(!utils::file_test("-f", "~/Dropbox/radtools_vignette_data/prostate/000008.dcm")) {
  knitr::opts_chunk$set(eval = FALSE)
  message("Note: code examples will not be evaluated because they depend on local data.")
}

Overview

Radtools forwards to oro.dicom and oro.nifti under the hood for reading images and extracting data from them. The added value of radtools is to provide simple, uniform functions to access metadata in convenient formats, reducing the need for code duplication or for understanding the finer points of oro.dicom and oro.nifti. In this vignette we compare some of radtools' functionality for metadata extraction to equivalent code using oro.dicom and oro.nifti.

Load sample data:

dicom_data <- radtools::read_dicom("~/Dropbox/radtools_vignette_data/prostate/")
nifti_data_rad <- radtools::read_nifti1("~/Dropbox/radtools_vignette_data/filtered_func_data.nii.gz")
nifti_data_oro <- oro.nifti::readNIfTI("~/Dropbox/radtools_vignette_data/filtered_func_data.nii.gz")

Extracting image metadata

Get image dimensions and number of slices

radtools

The functions radtools::img_dimensions and radtools::num_slices work for both DICOM and NIfTI images.

radtools::img_dimensions(dicom_data)
radtools::img_dimensions(nifti_data_rad)
radtools::num_slices(dicom_data)
radtools::num_slices(nifti_data_rad)

oro

The oro packages do not contain direct functions for this. For oro.dicom, you can use base::dim on the extracted 3D matrix. For oro.nifti, you can use base::dim on the NIfTI object directly.

mat_dicom <- oro.dicom::create3D(dicom_data)
dim(mat_dicom)
dim(nifti_data_oro)
dim(mat_dicom)[3] # Number of slices
dim(nifti_data_oro)[3] # Number of slices

Get the actual metadata attributes present in a dataset

The radtools::header_fields function works for both DICOM and NIfTI data.

DICOM

radtools

fields <- radtools::header_fields(dicom_data)
head(fields, 10)

oro.dicom

oro.dicom does not contain a direct function for this. You can get the metadata table with oro.dicom::dicomTable and extract its column names. You have to pass dicom_data$hdr instead of dicom_data directly.

tab <- oro.dicom::dicomTable(dicom_data$hdr)
fields <- colnames(tab)
head(fields, 10)

NIfTI

All NIfTI datasets have the same metadata attributes.

radtools

fields <- radtools::header_fields(nifti_data_rad)
head(fields, 10)

oro.nifti

oro.nifti does not provide a function to get the names of metadata attributes; accessors for each individual metadata attribute are provided.

Get DICOM metadata value across slices as a list

Both radtools and oro.dicom provide functions to get the values of a metadata attribute across slices by the attribute name.

radtools

radtools::header_value(dicom_data, "SliceLocation")

oro.dicom

In oro.dicom, you have to pass dicom_data$hdr instead of dicom_data directly.

oro.dicom::extractHeader(dicom_data$hdr, "SliceLocation")

Get the metadata for entire dataset as a table (DICOM) or list (NIFTI)

DICOM

Both radtools and oro.dicom provide functions to extract all metadata as a matrix. See below for the different matrix formats.

radtools

mat <- radtools::dicom_header_as_matrix(dicom_data)
kable(mat[1:10, 1:6])

oro.dicom

In oro.dicom, you have to pass dicom_data$hdr instead of dicom_data directly. The row names of the matrix are the .dcm file names.

mat <- oro.dicom::dicomTable(dicom_data$hdr)
kable(mat[1:10, 1:6])

NIfTI

radtools

nifti_header_vals <- radtools::nifti1_header_values(nifti_data_rad)
head(nifti_header_vals[names(nifti_header_vals) != ".Data"])

oro.nifti

This functionality is not available in oro.nifti. Accessors are provided for individual metadata attributes.

Get constant (across slices) DICOM attributes and their values

In DICOM datasets, many attributes have constant values across all slices. These are properties of the data acquisition as a whole, as opposed to individual slices.

radtools

Radtools provides a direct function to get these dataset attributes as a named list. Numeric values are returned as numbers by default.

const_attributes <- radtools::dicom_constant_header_values(dicom_data)
head(const_attributes)

oro.dicom

With oro.dicom, a few lines of code are required to access overall dataset attributes. All attributes are returned as strings.

tab <- oro.dicom::dicomTable(dicom_data$hdr)
const_cols <- apply(tab, 2, function(x) {length(unique(x)) == 1})
const_attributes <- as.list(tab[1, const_cols])
head(const_attributes)

Extracting image data

radtools

The radtools::img_data_to_mat function works for both DICOM and NIfTI data.

mat_dicom <- radtools::img_data_to_mat(dicom_data)
dim(mat_dicom)
mat_nifti <- radtools::img_data_to_mat(nifti_data_rad)
dim(mat_nifti)

oro

oro.dicom and oro.nifti each have direct functions to get the image data as a matrix. Because of the different typical uses of these formats, the functions have different names.

mat_dicom <- oro.dicom::create3D(dicom_data)
dim(mat_dicom)
mat_nifti <- oro.nifti::img_data(nifti_data_oro)
dim(mat_nifti)

Viewing images

The radtools::view_slice function works for both DICOM and NIfTI datasets. For datasets with more than three dimensions, data can first be reduced to a 3D matrix with the generic function img_data_to_3D_mat and then radtools::view_slice_mat is agnostic to the original format of the data.

oro.dicom does not provide a direct view function, while oro.nifti does.

DICOM

radtools

radtools::view_slice(dicom_data, slice = 10)

oro.dicom

As oro.dicom does not provide a direct view function, a small amount of code is required.

mat <- oro.dicom::create3D(dicom_data)
m <- mat[,,10]
col <- grDevices::grey(0:64/64)
graphics::image(x = 1:nrow(m), y = 1:ncol(m), z = m, col = col, ann = FALSE)

NIfTI

radtools

mat <- radtools::img_data_to_3D_mat(nifti_data_rad, coord_extra_dim = 90)
radtools::view_slice_mat(mat, slice = 10)

oro.nifti

oro.nifti provides a direct image function:

oro.nifti::image(nifti_data_oro, z = 10, w = 90, plot.type = "single")

DICOM standard

radtools

Radtools provides functions to explore the DICOM standard itself.

Get the DICOM standard version used

radtools::dicom_standard_version()
radtools::dicom_standard_web()
radtools::dicom_standard_timestamp()

Get lists of all valid attributes

Tags:

tags <- radtools::dicom_all_valid_header_tags()
head(tags, 10)

Names:

names <- radtools::dicom_all_valid_header_names()
head(names, 10)

Keywords:

keywords <- radtools::dicom_all_valid_header_keywords()
head(keywords, 10)

Search the DICOM standard for attribute names and keywords matching a given string:

radtools::dicom_search_header_names("manufacturer")
radtools::dicom_search_header_keywords("manufacturer")

oro.dicom

This functionality is not provided in oro.dicom.

Session info

sessionInfo()

radtools documentation built on May 1, 2019, 7:51 p.m.