R: Working with MRI images stored in NIfTI, Analyze and MGH...

identifyImageFileNames {tractor.base} | R Documentation

## 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

    identifyImageFileNames(fileName, fileType = NULL, errorIfMissing = TRUE,
      ...)

    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)

    registerPathHandler(regex, handler)

### Arguments

`fileName, from, to` | File names, with or without appropriate extension.
`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.
`errorIfMissing` | Logical value: raise an error if no suitable files were found?
`...` | Additional arguments to custom path handlers.
`overwrite` | 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.
`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"`).
`deleteOriginals` | Logical value: if `TRUE`, `copyImageFiles` performs a move rather than a copy.
`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.
`image` | An `MriImage` object.
`maxSize` | 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.
`writeTags` | Logical value: should tags be written in YAML format to an auxiliary file?
`regex` | A regular expression.
`handler` | A function taking and returning a string.

### 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.

`registerPathHandler` allows special syntaxes to be used for image paths, and is for advanced use only.

### Value

`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:

fileStem

  The file name without extension.

headerFile

  The full header file name.

imageFile

  The full image file name.

format

  The format of the files (`"Nifti"`, `"Analyze"` or `"Mgh"`). Not returned by `writeImageFile`.

`copyImageFiles` and `symlinkImageFiles` are called for their side effects.

### 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. http://www.jstatsoft.org/v44/i08/.

### See Also

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

[Package tractor.base version 3.2.2 Index]