Functions for reading, writing, locating, copying and removing MRI images stored in NIfTI, Analyze and MGH formats.
identifyImageFileNames(fileName, fileType = NULL, errorIfMissing = TRUE,
auxiliaries = c("dirs", "lut", "tags"), ...)imageFileExists(fileName, fileType = NULL)
removeImageFiles(fileName, ...)
symlinkImageFiles(from, to, overwrite = FALSE, relative = TRUE, ...)
copyImageFiles(from, to, overwrite = FALSE, deleteOriginals = FALSE, ...)
readImageFile(fileName, fileType = NULL, metadataOnly = FALSE,
volumes = NULL, sparse = FALSE, mask = NULL, reorder = TRUE, ...)
writeImageFile(image, fileName = NULL, fileType = NA, overwrite = TRUE,
maxSize = NULL, writeTags = FALSE)
readImageFile
returns an MriImage
object. imageFileExists
returns TRUE
if an existing file
with the specified name exists (all file extensions are checked), and
FALSE
otherwise. removeImageFiles
returns the result of
unlink
applied to all relevant files. writeImageFile
and identifyImageFileNames
return a list with the following elements,
describing the identified or written files:
The file name without extension.
The full header file name.
The full image file name.
The format of the files ("Nifti"
, "Analyze"
or "Mgh"
). Not returned by writeImageFile
.
copyImageFiles
and symlinkImageFiles
are called for their
side effects.
File names, with or without appropriate extension.
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.
Logical value: raise an error if no suitable files were found?
A character vector of auxiliary file suffixes to search for.
For identifyImageFileNames
, additional arguments to
resolvePath
. Elsewhere, additional arguments to
identifyImageFileNames
.
Logical value: overwrite an existing image file? For
writeImageFile
, an error will be raised if there is an existing
file and this is set to FALSE.
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"
).
Logical value: if TRUE
, copyImageFiles
performs a move rather than a copy.
Logical value: if TRUE
, only metadata are read
into the object.
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.
Logical value: should the image data be stored in a
SparseArray
object?
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
.
Logical value: should the image data be reordered to LAS? This is recommended in most circumstances.
An MriImage
object.
If not NULL
, the maximum number of bytes per pixel to
use when storing the data. This can lead to a substantial loss of
precision, and is usually not desirable. Only used when writing to the
NIfTI file format.
Logical value: should tags be written in YAML format to an auxiliary file?
Jon Clayden
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.
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. https://www.jstatsoft.org/v44/i08/.
The RNifti
package, and MriImage
.