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)
#> [1] 384 384  19
radtools::img_dimensions(nifti_data_rad)
#> [1]  64  64  21 180
radtools::num_slices(dicom_data)
#> [1] 19
radtools::num_slices(nifti_data_rad)
#> [1] 21

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)
#> [1] 384 384  19
dim(nifti_data_oro)
#> [1]  64  64  21 180
dim(mat_dicom)[3] # Number of slices
#> [1] 19
dim(nifti_data_oro)[3] # Number of slices
#> [1] 21

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)
#>  [1] "AccessionNumber"          "AcquisitionDate"         
#>  [3] "AcquisitionMatrix"        "AcquisitionNumber"       
#>  [5] "AcquisitionTime"          "AdditionalPatientHistory"
#>  [7] "AngioFlag"                "BitsAllocated"           
#>  [9] "BitsStored"               "BodyPartExamined"

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)
#>  [1] "0002-0000-GroupLength"               
#>  [2] "0002-0001-FileMetaInformationVersion"
#>  [3] "0002-0002-MediaStorageSOPClassUID"   
#>  [4] "0002-0003-MediaStorageSOPInstanceUID"
#>  [5] "0002-0010-TransferSyntaxUID"         
#>  [6] "0002-0012-ImplementationClassUID"    
#>  [7] "0002-0013-ImplementationVersionName" 
#>  [8] "0008-0005-SpecificCharacterSet"      
#>  [9] "0008-0008-ImageType"                 
#> [10] "0008-0012-InstanceCreationDate"

NIfTI

All NIfTI datasets have the same metadata attributes.

radtools

fields <- radtools::header_fields(nifti_data_rad)
head(fields, 10)
#>  [1] ".Data"         "sizeof_hdr"    "data_type"     "db_name"      
#>  [5] "extents"       "session_error" "regular"       "dim_info"     
#>  [9] "dim_"          "intent_p1"

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")
#>  [1]  28.53097  22.53097   1.53097  25.53097  19.53097  16.53097  13.53097
#>  [8]  10.53097   7.53097  -1.46903  -4.46903  -7.46903 -10.46903 -13.46903
#> [15] -16.46903 -19.46903 -22.46903 -25.46903   4.53097

oro.dicom

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

oro.dicom::extractHeader(dicom_data$hdr, "SliceLocation")
#>  [1]  28.53097  22.53097   1.53097  25.53097  19.53097  16.53097  13.53097
#>  [8]  10.53097   7.53097  -1.46903  -4.46903  -7.46903 -10.46903 -13.46903
#> [15] -16.46903 -19.46903 -22.46903 -25.46903   4.53097

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])

group	element	name	code	slice_1	slice_2
0002	0000	GroupLength	UL	196	196
0002	0001	FileMetaInformationVersion	OB
0002	0002	MediaStorageSOPClassUID	UI	1.2.840.10008.5.1.4.1.1.4	1.2.840.10008.5.1.4.1.1.4
0002	0003	MediaStorageSOPInstanceUID	UI	1.3.6.1.4.1.14519.5.2.1.7307.2101.420604470287150790758949858236	1.3.6.1.4.1.14519.5.2.1.7307.2101.192741832082705219013781007567
0002	0010	TransferSyntaxUID	UI	1.2.840.10008.1.2.1	1.2.840.10008.1.2.1
0002	0012	ImplementationClassUID	UI	1.2.40.0.13.1.1.1	1.2.40.0.13.1.1.1
0002	0013	ImplementationVersionName	SH	dcm4che-1.4.31	dcm4che-1.4.31
0008	0005	SpecificCharacterSet	CS	ISO_IR 100	ISO_IR 100
0008	0008	ImageType	CS	ORIGINAL PRIMARY M NORM DIS2D	ORIGINAL PRIMARY M NORM DIS2D
0008	0012	InstanceCreationDate	DA	20030816	20030816

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])

	0002-0000-GroupLength	0002-0002-MediaStorageSOPClassUID	0002-0003-MediaStorageSOPInstanceUID	0002-0010-TransferSyntaxUID	0002-0012-ImplementationClassUID
/Users/Pamela/Dropbox/radtools_vignette_data/prostate//000000.dcm	196	1.2.840.10008.5.1.4.1.1.4	1.3.6.1.4.1.14519.5.2.1.7307.2101.420604470287150790758949858236	1.2.840.10008.1.2.1	1.2.40.0.13.1.1.1
/Users/Pamela/Dropbox/radtools_vignette_data/prostate//000001.dcm	196	1.2.840.10008.5.1.4.1.1.4	1.3.6.1.4.1.14519.5.2.1.7307.2101.192741832082705219013781007567	1.2.840.10008.1.2.1	1.2.40.0.13.1.1.1
/Users/Pamela/Dropbox/radtools_vignette_data/prostate//000002.dcm	196	1.2.840.10008.5.1.4.1.1.4	1.3.6.1.4.1.14519.5.2.1.7307.2101.161930459406981809223699404886	1.2.840.10008.1.2.1	1.2.40.0.13.1.1.1
/Users/Pamela/Dropbox/radtools_vignette_data/prostate//000003.dcm	196	1.2.840.10008.5.1.4.1.1.4	1.3.6.1.4.1.14519.5.2.1.7307.2101.287759978322423706867384307484	1.2.840.10008.1.2.1	1.2.40.0.13.1.1.1
/Users/Pamela/Dropbox/radtools_vignette_data/prostate//000004.dcm	196	1.2.840.10008.5.1.4.1.1.4	1.3.6.1.4.1.14519.5.2.1.7307.2101.173407198604874164965409301481	1.2.840.10008.1.2.1	1.2.40.0.13.1.1.1
/Users/Pamela/Dropbox/radtools_vignette_data/prostate//000005.dcm	196	1.2.840.10008.5.1.4.1.1.4	1.3.6.1.4.1.14519.5.2.1.7307.2101.116293388259950259079972479579	1.2.840.10008.1.2.1	1.2.40.0.13.1.1.1
/Users/Pamela/Dropbox/radtools_vignette_data/prostate//000006.dcm	196	1.2.840.10008.5.1.4.1.1.4	1.3.6.1.4.1.14519.5.2.1.7307.2101.150881934484752844380961750973	1.2.840.10008.1.2.1	1.2.40.0.13.1.1.1
/Users/Pamela/Dropbox/radtools_vignette_data/prostate//000007.dcm	196	1.2.840.10008.5.1.4.1.1.4	1.3.6.1.4.1.14519.5.2.1.7307.2101.758120058350565757737746811841	1.2.840.10008.1.2.1	1.2.40.0.13.1.1.1
/Users/Pamela/Dropbox/radtools_vignette_data/prostate//000008.dcm	196	1.2.840.10008.5.1.4.1.1.4	1.3.6.1.4.1.14519.5.2.1.7307.2101.270530193269111656153914349218	1.2.840.10008.1.2.1	1.2.40.0.13.1.1.1
/Users/Pamela/Dropbox/radtools_vignette_data/prostate//000009.dcm	196	1.2.840.10008.5.1.4.1.1.4	1.3.6.1.4.1.14519.5.2.1.7307.2101.143413825106637367991836405871	1.2.840.10008.1.2.1	1.2.40.0.13.1.1.1

NIfTI

radtools

nifti_header_vals <- radtools::nifti1_header_values(nifti_data_rad)
head(nifti_header_vals[names(nifti_header_vals) != ".Data"])
#> $sizeof_hdr
#> [1] 348
#> 
#> $data_type
#> [1] ""
#> 
#> $db_name
#> [1] ""
#> 
#> $extents
#> [1] 0
#> 
#> $session_error
#> [1] 0
#> 
#> $regular
#> [1] "r"

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)
#> $GroupLength
#> [1] 196
#> 
#> $FileMetaInformationVersion
#> [1] "\001"
#> 
#> $MediaStorageSOPClassUID
#> [1] "1.2.840.10008.5.1.4.1.1.4"
#> 
#> $TransferSyntaxUID
#> [1] "1.2.840.10008.1.2.1"
#> 
#> $ImplementationClassUID
#> [1] "1.2.40.0.13.1.1.1"
#> 
#> $ImplementationVersionName
#> [1] "dcm4che-1.4.31"

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)
#> $`0002-0000-GroupLength`
#> [1] "196"
#> 
#> $`0002-0001-FileMetaInformationVersion`
#> [1] "\001"
#> 
#> $`0002-0002-MediaStorageSOPClassUID`
#> [1] "1.2.840.10008.5.1.4.1.1.4"
#> 
#> $`0002-0010-TransferSyntaxUID`
#> [1] "1.2.840.10008.1.2.1"
#> 
#> $`0002-0012-ImplementationClassUID`
#> [1] "1.2.40.0.13.1.1.1"
#> 
#> $`0002-0013-ImplementationVersionName`
#> [1] "dcm4che-1.4.31"

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)
#> [1] 384 384  19
mat_nifti <- radtools::img_data_to_mat(nifti_data_rad)
dim(mat_nifti)
#> [1]  64  64  21 180

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)
#> [1] 384 384  19
mat_nifti <- oro.nifti::img_data(nifti_data_oro)
dim(mat_nifti)
#> [1]  64  64  21 180

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()
#> [1] "PS3.6 2018d"
radtools::dicom_standard_web()
#> [1] "http://dicom.nema.org/medical/dicom/current/output/html/part06.html"
radtools::dicom_standard_timestamp()
#> [1] "2018-10-15 15:45:47 MDT"

Get lists of all valid attributes

Tags:

tags <- radtools::dicom_all_valid_header_tags()
head(tags, 10)
#>  [1] "(0002,0000)" "(0002,0001)" "(0002,0002)" "(0002,0003)" "(0002,0010)"
#>  [6] "(0002,0012)" "(0002,0013)" "(0002,0016)" "(0002,0017)" "(0002,0018)"

Names:

names <- radtools::dicom_all_valid_header_names()
head(names, 10)
#>  [1] ""                                               
#>  [2] "2D Degree of Freedom Axis"                      
#>  [3] "2D Degree of Freedom Sequence"                  
#>  [4] "2D Implant Template Group Member Matching Axes" 
#>  [5] "2D Implant Template Group Member Matching Point"
#>  [6] "2D Line Coordinates"                            
#>  [7] "2D Line Coordinates Sequence"                   
#>  [8] "2D Mating Axes"                                 
#>  [9] "2D Mating Feature Coordinates Sequence"         
#> [10] "2D Mating Point"

Keywords:

keywords <- radtools::dicom_all_valid_header_keywords()
head(keywords, 10)
#>  [1] ""                             "AbortFlag"                   
#>  [3] "AbortReason"                  "AbsoluteChannelDisplayScale" 
#>  [5] "AbstractPriorCodeSequence"    "AbstractPriorValue"          
#>  [7] "AccessionNumber"              "AccessoryCode"               
#>  [9] "AcquiredImageAreaDoseProduct" "AcquiredSoundpathLength"

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

radtools::dicom_search_header_names("manufacturer")
#>  [1] "Application Manufacturer"                          
#>  [2] "Application Setup Manufacturer"                    
#>  [3] "Component Manufacturer"                            
#>  [4] "Detector Manufacturer Name"                        
#>  [5] "Detector Manufacturer's Model Name"                
#>  [6] "Hardcopy Device Manufacturer"                      
#>  [7] "Hardcopy Device Manufacturer's Model Name"         
#>  [8] "Information From Manufacturer Sequence"            
#>  [9] "IOL Manufacturer"                                  
#> [10] "Manufacturer"                                      
#> [11] "Manufacturer's Model Name"                         
#> [12] "Manufacturer's Related Model Group"                
#> [13] "Modifying Device Manufacturer"                     
#> [14] "Notification From Manufacturer Sequence"           
#> [15] "Receive Coil Manufacturer Name"                    
#> [16] "Secondary Capture Device Manufacturer"             
#> [17] "Secondary Capture Device Manufacturer's Model Name"
#> [18] "Source Applicator Manufacturer"                    
#> [19] "Source Manufacturer"                               
#> [20] "Transmit Coil Manufacturer Name"                   
#> [21] "Wedge Manufacturer Name"
radtools::dicom_search_header_keywords("manufacturer")
#>  [1] "ApplicationManufacturer"                    
#>  [2] "ApplicationSetupManufacturer"               
#>  [3] "ComponentManufacturer"                      
#>  [4] "DetectorManufacturerModelName"              
#>  [5] "DetectorManufacturerName"                   
#>  [6] "HardcopyDeviceManufacturer"                 
#>  [7] "HardcopyDeviceManufacturerModelName"        
#>  [8] "InformationFromManufacturerSequence"        
#>  [9] "IOLManufacturer"                            
#> [10] "Manufacturer"                               
#> [11] "ManufacturerModelName"                      
#> [12] "ManufacturerRelatedModelGroup"              
#> [13] "ModifyingDeviceManufacturer"                
#> [14] "NotificationFromManufacturerSequence"       
#> [15] "ReceiveCoilManufacturerName"                
#> [16] "SecondaryCaptureDeviceManufacturer"         
#> [17] "SecondaryCaptureDeviceManufacturerModelName"
#> [18] "SourceApplicatorManufacturer"               
#> [19] "SourceManufacturer"                         
#> [20] "TransmitCoilManufacturerName"               
#> [21] "WedgeManufacturerName"

oro.dicom

This functionality is not provided in oro.dicom.

Session info

sessionInfo()
#> R version 3.5.2 (2018-12-20)
#> Platform: x86_64-apple-darwin15.6.0 (64-bit)
#> Running under: macOS Mojave 10.14.3
#> 
#> Matrix products: default
#> BLAS: /Library/Frameworks/R.framework/Versions/3.5/Resources/lib/libRblas.0.dylib
#> LAPACK: /Library/Frameworks/R.framework/Versions/3.5/Resources/lib/libRlapack.dylib
#> 
#> locale:
#> [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] knitr_1.21
#> 
#> loaded via a namespace (and not attached):
#>  [1] tidyselect_0.2.5    xfun_0.5            purrr_0.3.0        
#>  [4] splines_3.5.2       lattice_0.20-38     colorspace_1.4-0   
#>  [7] htmltools_0.3.6     yaml_2.2.0          base64enc_0.1-3    
#> [10] survival_2.43-3     rlang_0.3.1         pillar_1.3.1       
#> [13] foreign_0.8-71      glue_1.3.0          RColorBrewer_1.1-2 
#> [16] plyr_1.8.4          stringr_1.4.0       munsell_0.5.0      
#> [19] gtable_0.2.0        RNifti_0.10.0       htmlwidgets_1.3    
#> [22] oro.dicom_0.5.0     evaluate_0.13       latticeExtra_0.6-28
#> [25] highr_0.7           htmlTable_1.13.1    Rcpp_1.0.0         
#> [28] acepack_1.4.1       scales_1.0.0        backports_1.1.3    
#> [31] checkmate_1.9.1     Hmisc_4.2-0         abind_1.4-5        
#> [34] gridExtra_2.3       ggplot2_3.1.0       radtools_1.0.5     
#> [37] digest_0.6.18       stringi_1.3.1       dplyr_0.8.0.1      
#> [40] grid_3.5.2          tools_3.5.2         bitops_1.0-6       
#> [43] magrittr_1.5        lazyeval_0.2.1      tibble_2.0.1       
#> [46] Formula_1.2-3       cluster_2.0.7-1     crayon_1.3.4       
#> [49] pkgconfig_2.0.2     Matrix_1.2-15       data.table_1.12.0  
#> [52] oro.nifti_0.9.1     assertthat_0.2.0    rmarkdown_1.11     
#> [55] rstudioapi_0.9.0    R6_2.4.0            rpart_4.1-13       
#> [58] nnet_7.3-12         compiler_3.5.2

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

Pamela Russell

2019-04-16

Overview

Extracting image metadata

Get image dimensions and number of slices

radtools

oro

Get the actual metadata attributes present in a dataset

DICOM

radtools

oro.dicom

NIfTI

radtools

oro.nifti

Get DICOM metadata value across slices as a list

radtools

oro.dicom

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

DICOM

radtools

oro.dicom

NIfTI

radtools

oro.nifti

Get constant (across slices) DICOM attributes and their values

radtools

oro.dicom

Extracting image data

radtools

oro

Viewing images

DICOM

radtools

oro.dicom

NIfTI

radtools

oro.nifti

DICOM standard

radtools

Get the DICOM standard version used

Get lists of all valid attributes

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

oro.dicom

Session info