newMriImageFromFile: Working with MRI images stored in NIfTI, Analyze and MGH formats

Description

Functions for reading, writing, locating, copying and removing MRI images stored in NIfTI, Analyze and MGH formats.

Usage

newMriImageFromFile(fileName, fileType = NULL, volumes = NULL, sparse = FALSE, mask = NULL)
newMriImageMetadataFromFile(fileName, fileType = NULL)
writeMriImageToFile(image, fileName = NULL, fileType = NA, datatype = NULL, overwrite = TRUE)
identifyImageFileNames(fileName, fileType = NULL, errorIfMissing = TRUE)
imageFileExists(fileName, fileType = NULL)
removeImageFilesWithName(fileName)
copyImageFiles(from, to, overwrite = FALSE, deleteOriginals = FALSE)
symlinkImageFiles(from, to, overwrite = FALSE, relative = TRUE)

Arguments

fileName, from, to

File names, with or without appropriate extension.

image

An MriImage object.

fileType

A character vector of length one, giving the file type required or expected. If this option is missing, the file type used for writing images will be taken from the tractorFileType option. See Details.

volumes

An optional integer vector specifying a subset of volumes to read (generally to save memory). If given, only the requested volumes in the 4D file will be read.

sparse

Logical value: should the image data be stored in a SparseArray object?

mask

An optional MriImage object representing a mask, outside of which the image to be read should be considered to be zero. This can be used to save memory when only a small part of a large image is of interest. Ignored

datatype

A storage data type. See getDataTypeByNiftiCode.

overwrite

Logical value: overwrite an existing image file? For writeMriImageToFile, an error will be raised if there is an existing file and this is set to FALSE.

errorIfMissing

Logical value: raise an error if no suitable files were found?

deleteOriginals

Logical value: if TRUE, copyImageFiles performs a move rather than a copy.

relative

Logical value: if TRUE, the path stored in the symlink will be relative (e.g. "../some_dir/some_image.nii") rather than absolute (e.g. "/path/to/some_dir/some_image.nii").

Value

newMriImageFromFile and newMriImageMetadataFromFile return the appropriate image or metadata object. imageFileExists returns TRUE if an existing file with the specified name exists (all file extensions are checked), and FALSE otherwise. removeImageFilesWithName returns the result of unlink applied to all relevant files. writeMriImageToFile and identifyImageFileNames return a list with the following elements, describing the identified or written files:
fileStemThe file name without extension.
headerFileThe full header file name.
imageFileThe full image file name.
formatThe format of the files ("Nifti", "Analyze" or "Mgh"). Not returned by writeMriImageToFile.
copyImageFiles and symlinkImageFiles are called for their side effects.

Details

NIfTI and Analyze are related formats for storing magnetic resonance images. NIfTI is a more recent extension of Analyze, and contains more specific information about, for example, the orientation of the image. Its use is therefore recommended where possible. MGH format is used by the popular image processing package FreeSurfer. These formats use a number of different file extensions, but the details are abstracted away from the user by these functions. TractoR does not allow for files with the same basic name using multiple Analyze/NIfTI/MGH formats in a single directory (e.g. "foo.nii" AND "foo.img"), and these functions will produce an error if multiple compatible files exist.

Suitable values for fileType (and the tractorFileType option, which is used as a default) are ANALYZE, NIFTI, NIFTI_PAIR (the two-file NIfTI format), MGH, ANALYZE_GZ, NIFTI_GZ, NIFTI_PAIR_GZ and MGH_GZ. The latter four are gzipped versions of the former four. NIFTI_GZ is recommended unless there is a need for one of the others. This is the default value for the tractorFileType option, but that can be changed using a call to options, or by setting the TRACTOR_FILETYPE environment variable before loading the tractor.base package. Since multiple files may be involved, copying, moving or symlinking images is not trivial. copyImageFiles and symlinkImageFiles are wrappers around the standard functions file.copy and file.symlink which handle this complexity.

References

Please cite the following reference when using TractoR in your work: