readImageFile: Reading and writing image files

In tractor.base: Read, Manipulate and Visualise Magnetic Resonance Images

Reading and writing image files

Description

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

Usage

readImageFile(fileName, metadataOnly = FALSE, volumes = NULL,
  sparse = FALSE, mask = NULL, reorder = TRUE, ...)

writeImageFile(image, fileName = NULL,
  fileType = getOption("tractorFileType"), overwrite = TRUE,
  datatype = "fit", writeTags = FALSE)

Arguments

fileName	A file path, with or without appropriate extension.
metadataOnly	Logical value: if TRUE, only metadata are read into the object.
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 if sparse is not TRUE.
reorder	Logical value: should the image data be reordered to LAS? This is recommended in most circumstances.
...	Additional arguments to identifyImageFileNames.
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.
overwrite	Logical value: overwrite an existing image file? An error will be raised if there is an existing file and this is set to FALSE.
datatype	A datatype string, such as "uint8" or "float", specifying the pixel datatype to use when storing the data. If specified, this must be a type supported by the requested (or default) file format. The default, "fit", results in a datatype being chosen that is wide enough to fit the range of the data elements. An error will arise if there's no such type.
writeTags	Logical value: should tags be written in YAML format to an auxiliary file?

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, and MRtrix format by the software of the same name. 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/MRtrix 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 for writing) are "NIFTI", "NIFTI_PAIR" (the two-file NIfTI format), "MGH", and corresponding gzipped versions of these with "_GZ" appended. File types "ANALYZE" and "MRTRIX", and "_GZ" variants, are additionally available for reading only. "NIFTI_GZ" 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.

Value

readImageFile returns an MriImage object. writeImageFile returns a list giving details of the file paths that were written to.

Author(s)

Jon Clayden

References

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

J.D. Clayden, S. Muñoz Maniega, A.J. Storkey, M.D. King, M.E. Bastin & C.A. Clark (2011). TractoR: Magnetic resonance imaging and tractography with R. Journal of Statistical Software 44(8):1-18. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.18637/jss.v044.i08")}.

See Also

The NIfTI-1 standard (http://nifti.nimh.nih.gov/nifti-1) and MriImage.

tractor.base documentation built on Nov. 5, 2025, 6:18 p.m.