Read and write volume data

Read and write volume data ('MRI', 'CT', etc.) in 'NIfTI' or 'MGH' formats. Please use read_volume and write_volume for high-level function. These functions will call other low-level functions internally.

Usage

read_volume(file, header_only = FALSE, format = c("auto", "nifti", "mgh"), ...)

write_volume(x, con, format = c("auto", "nifti", "mgh"), ...)

io_read_mgz(file, header_only = FALSE)

io_write_mgz(x, con, ...)

# S3 method for class 'ieegio_volume'
io_write_mgz(x, con, ...)

# S3 method for class 'ieegio_mgh'
io_write_mgz(x, con, ...)

# S3 method for class 'nifti'
io_write_mgz(x, con, ...)

# S3 method for class 'niftiImage'
io_write_mgz(x, con, ...)

# S3 method for class 'ants.core.ants_image.ANTsImage'
io_write_mgz(x, con, ...)

# S3 method for class 'array'
io_write_mgz(x, con, vox2ras = NULL, ...)

io_read_nii(
  file,
  method = c("oro", "rnifti", "ants"),
  header_only = FALSE,
  ...
)

io_write_nii(x, con, ...)

# S3 method for class 'ieegio_nifti'
io_write_nii(x, con, ...)

# S3 method for class 'ants.core.ants_image.ANTsImage'
io_write_nii(x, con, ...)

# S3 method for class 'niftiImage'
io_write_nii(x, con, ...)

# S3 method for class 'nifti'
io_write_nii(x, con, gzipped = NA, ...)

# S3 method for class 'ieegio_mgh'
io_write_nii(x, con, ...)

# S3 method for class 'array'
io_write_nii(x, con, vox2ras = NULL, ...)

Format

format of the file; default is auto-detection, other choices are 'nifti' and 'mgh';

Arguments

file

file path to read volume data

header_only

whether to read header data only; default is FALSE

format

format of the file to be written; choices are 'auto', 'nifti' or 'mgh'; default is to 'auto' detect the format based on file names, which will save as a 'MGH' file when file extension is 'mgz' or 'mgh', otherwise 'NIfTI' format. We recommend explicitly setting this argument

...

passed to other methods

x

volume data (such as 'NIfTI' image, array, or 'MGH') to be saved

con

file path to store image

vox2ras

a 4x4 transform matrix from voxel indexing (column, row, slice) to scanner (often 'T1-weighted' image) 'RAS' (right-anterior-superior) coordinate

method

method to read the file; choices are 'oro' (using readNIfTI), 'rnifti' (using readNifti), and 'ants' (using as_ANTsImage).

gzipped

for writing 'nii' data: whether the file needs to be compressed; default is inferred from the file name. When the file ends with 'nii', then no compression is used; otherwise the file will be compressed. If the file name does not end with 'nii' nor 'nii.gz', then the file extension will be added automatically.

Value

imaging readers return ieegio_volume objects.

Examples

library(ieegio)

nifti_file <- "brain.demosubject.nii.gz"

# Use `ieegio_sample_data(nifti_file)`
#   to download sample data


if( ieegio_sample_data(nifti_file, test = TRUE) ) {

# ---- NIfTI examples ---------------------------------------------

file <- ieegio_sample_data(nifti_file)

# basic read
vol <- read_volume(file)

# voxel to scanner RAS
vol$transforms$vox2ras

# to freesurfer surface
vol$transforms$vox2ras_tkr

# to FSL
vol$transforms$vox2fsl

image(vol$data[,,128], asp = 1, axes = FALSE)

# ---- using other methods --------------------------------------
# default
vol <- read_volume(file, method = "oro", format = "nifti")
vol$header

# lazy-load nifti
vol2 <- read_volume(file, method = "rnifti", format = "nifti")
vol2$header

# Using ANTsPyx
vol3 <- read_volume(file, method = "ants", format = "nifti")
vol3$header

# ---- write --------------------------------------------------------

# write as NIfTI
f <- tempfile(fileext = ".nii.gz")

write_volume(vol, f, format = "nifti")

# alternative method
write_volume(vol$header, f, format = "nifti")

# write to mgz/mgh
f2 <- tempfile(fileext = ".mgz")

write_volume(vol, f, format = "mgh")

# clean up
unlink(f)
unlink(f2)

}