imageFiles: Image file sets

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

Image file sets

Description

TractoR supports several medical imaging file formats, some of which are made up of multiple files on disk or have compressed and uncompressed variants. There is also support for auxiliary "sidecar" files, which have the same path stem as the associated image files but different suffixes, and contain additional metadata. Typically the image files are in a binary format for space-efficiency, while any auxiliary files are in text-based formats for easier human readability. This interface, and the unpinning reference classes, handle and abstract away this complexity.

Usage

imageFiles(paths = NULL)

imageFileExists(fileName)

removeImageFiles(fileName, ...)

symlinkImageFiles(from, to, overwrite = FALSE, relative = TRUE, ...)

copyImageFiles(from, to, overwrite = FALSE, deleteOriginals = FALSE, ...)

Arguments

paths	Optionally, a character vector of image paths with or without suitable suffixes.
fileName, from	Character vectors of image paths.
...	Currently unused.
to	Character vector of target file names, or a single existing directory to copy or symlink into.
overwrite	Logical value: if TRUE, existing files will be overwritten; otherwise creating files with existing names will just fail.
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.

Details

The imageFiles function returns either a preinitialised instance of the ImageFileSet class, which handles file set logic in the abstract, or (if given a vector of paths as an argument) calls that instance's atPaths method, which facilitates handling specific files. If non-default parameters to the class constructor are required then a custom ImageFileSet object can be created directly instead.

imageFileExists, removeImageFiles, symlinkImageFiles and copyImageFiles are simple wrapper functions that exist for backwards compatibility. copyImageFiles(from, to), for example, is equivalent to imageFiles(from)$copy(to).

Value

If paths is NULL, imageFiles returns a singleton reference object of class ImageFileSet which can be used to identify and manipulate image files anywhere on the file system. If paths is specified, an S3 object of class fileSetHandle, a list of functions which can be used to manipulate the actual files at those paths. The functions are

stems()

Return the file stems associated with the paths.

info()

Return information about existing files, as a list with one element per path. An element will be NULL if no corresponding files currently exist.

read(...)

Read the images into memory and return them as MriImage objects.

copy(target, overwrite=TRUE)

Copy the files to target paths (new file names or a directory).

delete()

Delete the files or any map reference to them.

map(target, overwrite=TRUE, relative=TRUE)

Map the files to a new location (see FileMap for details).

move(target, overwrite=TRUE)

Move the files to target paths (new file names or a directory).

present()

Return Boolean values indicating whether or not files exist at each path.

symlink(target, overwrite=TRUE, relative=TRUE)

Symlink the files to target paths (if supported by the OS and file system).

imageFileExists returns a logical vector indicating whether or not valid image files exist at each specified path. Other functions 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. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.18637/jss.v044.i08")}.

See Also

Using ImageFileSet provides a lower-level and more flexible interface; readImageFile can be used if you just want to read an image into memory.

Examples

path <- system.file("extdata", "analyze", "maskedb0.img.gz",
  package="tractor.base")
im <- imageFiles(path)
print(im)
im$present()

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