Read a 3D or 4D NIFTI file into an fs.volume instance with complete header.

This function reads a NIFTI v1 or v2 file, or takes a nifti instance from the oro.nifti package, and computes the MGH header fields from the NIFTI header data, allowing for proper orientation of the contained image data (see mghheader.vox2ras and related functions). Files are read with the NIFTI reader of this package, so the oro.nifti package is only needed if a nifti instance is passed, or if reorient or extra arguments are used. Currently only few datatypes are supported, and the orientation can only be derived if the sform or qform header field is present.

Usage

read.fs.volume.nii(
  filepath,
  flatten = FALSE,
  with_header = FALSE,
  drop_empty_dims = FALSE,
  do_rotate = FALSE,
  reorient = FALSE,
  ...
)

Arguments

filepath: instance of class nifti from the oro.nifti package, or a path to a NIFTI file as a character string.
flatten: logical. Whether to flatten the return volume to a 1D vector. Useful if you know that this file contains 1D morphometry data.
with_header: logical. Whether to return the header as well. If TRUE, return an instance of class fs.volume for data with at least 3 dimensions, a named list with entries "data" and "header". The latter is another named list which contains the header data. These header entries exist: "dtype": int, one of: 0=MRI_UCHAR; 1=MRI_INT; 3=MRI_FLOAT; 4=MRI_SHORT. "voldim": integer vector. The volume (=data) dimensions. E.g., c(256, 256, 256, 1). These header entries may exist: "vox2ras_matrix" (exists if "ras_good_flag" is 1), "mr_params" (exists if "has_mr_params" is 1). See the mghheader.* functions, like mghheader.vox2ras.tkreg, to compute more information from the header fields.
drop_empty_dims: logical, whether to drop empty dimensions of the returned data
do_rotate: logical, whether to rotate 3D volumes to compensate for storage order. WIP.
reorient: logical, whether to let oro.nifti::readNIfTI reorient the data array to a standard orientation while reading it from a file. Defaults to FALSE, see the note below. Only relevant if filepath is a path, it is ignored if a nifti instance is passed. Using TRUE requires the oro.nifti package.
...: extra parameters passed to oro.nifti::readNIfTI. Leave this alone unless you know what you are doing. Note that reorient is passed explicitly by this function, so it cannot be set here. Passing any extra parameter makes the file be read by oro.nifti instead of by the NIFTI reader of this package, and thus requires the oro.nifti package.

Value

an fs.volume instance. The header fields are computed from the NIFTI header. The data array is returned in the raw NIFTI file storage order (first dimension fastest), which is also the order used by the MGH/MGZ format. For a file, the NIFTI data scaling fields scl_slope/scl_inter of the header are applied to the values while reading (this is what the oro.nifti package does for files as well), for an oro.nifti instance the values are returned as they are stored in the instance. If the NIFTI file contains sform or qform geometry information, the returned header contains a vox2ras_matrix entry in addition to the MGH header fields, just like the header returned by read.fs.mgh.

Note

The data array is not reoriented, because the NIFTI geometry is stored in the sform/qform header fields, and these describe the raw file storage order. Reorientation as performed by oro.nifti::readNIfTI(reorient = TRUE) permutes or flips the data array without updating the sform fields, so the data array would no longer match the header of the returned fs.volume (and thus not the vox2ras_matrix used to map voxel indices to coordinates). Using reorient = TRUE, or passing a nifti instance that was read with reorient = TRUE, is therefore discouraged and results in a warning.

Files are read with the NIFTI reader of this package, which reads both NIFTI v1 and NIFTI v2 files and does not require the oro.nifti package. Two details of the way oro.nifti used to read files are kept, so that the returned values do not change: the NIFTI data scaling fields (scl_slope/scl_inter) are applied to the values while reading (see the return value section), and voxel sizes that are stored as 0 for a used dimension (or that are not finite) are reported as 1.

This is not supposed to be used to read 1D morphometry data from NIFTI files generated by FreeSurfer (e.g., by converting lh.thickness to NIFTI using mri_convert): such files contain a single dimension, and the volume returned for them is degenerate. Use read.fs.morph to read morphometry data.

References

See https://nifti.nimh.nih.gov/nifti-1/ for the NIfTI-1 data format spec.

Examples

if (FALSE) { # \dontrun{
base_file <- "~/data/subject1_only/subject1/mri/brain"
# missing file ext.
mgh_file <- paste(base_file, ".mgz", sep = "")
# the standard MGH/MGZ file
nii_file <- paste(base_file, ".nii", sep = "")
# NIFTI file generated with mri_convert
brain_mgh <- read.fs.mgh(mgh_file, with_header = TRUE)
brain_nii <- read.fs.volume.nii(nii_file, with_header = TRUE)
all(brain_nii$data == brain_mgh$data)
# output: TRUE
all(mghheader.vox2ras(brain_nii) == mghheader.vox2ras(brain_mgh)) # output: TRUE
} # }

Read a 3D or 4D NIFTI file into an `fs.volume` instance with complete header.