| Title: | Read and Write NIfTI Files |
|---|---|
| Description: | Tools for reading and writing NIfTI-1.1 (NII) files, including optimized voxelwise read/write operations and a simplified method to write dataframes to NII. Specification of the NIfTI-1.1 format can be found here <https://nifti.nimh.nih.gov/nifti-1>. Scientific publication first using these tools Koscik TR, Man V, Jahn A, Lee CH, Cunningham WA (2020) <doi:10.1016/j.neuroimage.2020.116764> "Decomposing the neural pathways in a simple, value-based choice." Neuroimage, 214, 116764. |
| Authors: | Timothy R. Koscik [aut, cre, cph] |
| Maintainer: | Timothy Koscik <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.0 |
| Built: | 2026-06-02 07:59:16 UTC |
| Source: | https://github.com/cran/nifti.io |
Retrieve information from the NIfTI header of the specified file. The entire header can be retrieved as a list, or a single or subset of items can be specified as a character vector to get specific information. There are several special cases implemented including getting number of voxels, number of volumes, image spacing, and orientation.
info.nii(nii.file, field="hdr")info.nii(nii.file, field="hdr")
nii.file |
Full directory listing to NIfTI file. |
field |
A character vector of field names to be returned. |
Fields can take a number of different values indicating the entire header, a specific item or subset of header values or set of useful values.
Number of voxels in XYZ planes:
'dimensions', 'dims', 'size', 'sz', 'voxels', 'vxls', 'xyz'
Voxel spacing:
'space', 'spacing'
Number of Volumes:
'volumes', 'vols', 'trs'
Orientation fields:
'orientation'
Entire Header as list object:
'hdr'
Subset of specific header items:
'sizeof_hdr', 'data_type', 'db_name', 'extents', 'session_error', 'regular', 'dim_info', 'dim', 'intent_p1', 'intent_p2', 'intent_p3', 'intent_code', 'datatype', 'bitpix', 'slice_start', 'pixdim', 'vox_offset', 'scl_slope', 'scl_inter', 'slice_end', 'slice_code', 'xyzt_units', 'cal_max', 'cal_min', 'slice_duration', 'toffset', 'glmax', 'glmin', 'descrip', 'aux_file', 'qform_code', 'sform_code', 'quatern_b', 'quatern_c', 'quatern_d', 'qoffset_x', 'qoffset_y', 'qoffset_z', 'srow_x', 'srow_y', 'srow_z', 'intent_name', 'magic'
A vector or named list containing the requested output
Timothy R. Koscik <[email protected]>
# get filename for example NII file included in nifti.io package nii.eg <- system.file("extdata", "egBrain.nii", package="nifti.io") # get the number of voxels in the 3-dimensional volume of the specified image image.size <- info.nii(nii.file = nii.eg, field = "dimensions") # get the size in mm of the volume image.spacing <- info.nii(nii.file = nii.eg, field = "spacing") # get the number of volumes image.volumes <- info.nii(nii.file = nii.eg, field = "volumes") # get list containing orientation parameters image.orientation <- info.nii(nii.file = nii.eg, field = "orientation") # get entire header from NII file image.hdr <- info.nii(nii.file = nii.eg, field = "hdr") # get a specific element in the header image.hdr.datatype <- info.nii(nii.file = nii.eg, field = "datatype")# get filename for example NII file included in nifti.io package nii.eg <- system.file("extdata", "egBrain.nii", package="nifti.io") # get the number of voxels in the 3-dimensional volume of the specified image image.size <- info.nii(nii.file = nii.eg, field = "dimensions") # get the size in mm of the volume image.spacing <- info.nii(nii.file = nii.eg, field = "spacing") # get the number of volumes image.volumes <- info.nii(nii.file = nii.eg, field = "volumes") # get list containing orientation parameters image.orientation <- info.nii(nii.file = nii.eg, field = "orientation") # get entire header from NII file image.hdr <- info.nii(nii.file = nii.eg, field = "hdr") # get a specific element in the header image.hdr.datatype <- info.nii(nii.file = nii.eg, field = "datatype")
This function is used to initialize an empty NIfTI file. It creates the file volume-by-volume rather than a bulk array write operation such that massive arrays do not need to be loaded into memory
init.nii(new.nii, ref.nii=NULL, dims, pixdim=NULL, orient=NULL, datatype=16, init.value=NA)init.nii(new.nii, ref.nii=NULL, dims, pixdim=NULL, orient=NULL, datatype=16, init.value=NA)
new.nii |
Full file path for the file to be written, must have .nii extension |
ref.nii |
Full file path for reference image to use same space |
dims |
a numeric vector specifying the image dimensions, e.g., c(X,Y,Z,T) |
pixdim |
An 8 element numeric vector specifying the pixel dimensions image to be created. Should be in the format (a,x,y,z,t,b,c,d), the output from info.nii("example_file.nii", "pixdim") is the correct format |
orient |
A named list with the following elements, qform_code [integer(1)], sform_code [integer(1)], quatern_b [numeric(1)], quatern_c [numeric(1)], quatern_d [numeric(1)], qoffset_x [numeric(1)], qoffset_y [numeric(1)], qoffset_z [numeric(1)], srow_x [numeric(3)], srow_y [numeric(3)], srow_z [numeric(3)] |
datatype |
a numeric value indicating the type of tdata to be used in the new NII file, default=16 |
init.value |
value to use for all voxels to initialize NIfTI file, default=NA |
No return value
Timothy R. Koscik <[email protected]>
# get filename for example NII file included in nifti.io package ref.nii <- system.file("extdata", "egBrain.nii", package="nifti.io") # set new filename (using temporary directory for example) tdir <- tempdir() new.nii <- paste0(tdir, "/new.nii") # initialize new NII file init.nii(new.nii = new.nii, ref.nii = ref.nii)# get filename for example NII file included in nifti.io package ref.nii <- system.file("extdata", "egBrain.nii", package="nifti.io") # set new filename (using temporary directory for example) tdir <- tempdir() new.nii <- paste0(tdir, "/new.nii") # initialize new NII file init.nii(new.nii = new.nii, ref.nii = ref.nii)
Read indicated volume from NIfTI files.
read.nii.volume(nii.file, vol.num)read.nii.volume(nii.file, vol.num)
nii.file |
Full directory listing to a NIFTI file. File must not be gzipped. |
vol.num |
An integer indicating which volume to read. |
NIfTI files need to be unzipped before using this function or any other portions of the nifti.io package. This is necessary given the inconsistent way in which gzipped files are indexed (Some information on this is given in the documentation for the readBin function).
An array containing values from NIFTI volume.
Timothy R. Koscik <[email protected]>
# get filename for example NII file included in nifti.io package nii.eg <- system.file("extdata", "egBrain.nii", package="nifti.io") # read entire volume into array volume.values <- read.nii.volume(nii.file = nii.eg, vol.num = 1)# get filename for example NII file included in nifti.io package nii.eg <- system.file("extdata", "egBrain.nii", package="nifti.io") # read entire volume into array volume.values <- read.nii.volume(nii.file = nii.eg, vol.num = 1)
Read values from NIfTI files at given coordinates (x,y,z,t).
read.nii.voxel(nii.file, coords)read.nii.voxel(nii.file, coords)
nii.file |
Full directory listing to a NIfTI file. File must not be gzipped. |
coords |
A numeric vector conatining x,y,z,t coordinates indicating the location to read values. To read all volumes (timepoints) at an XYZ coordinate use 'Inf' for t, e.g., c(50,50,50,Inf). |
NIfTI files need to be unzipped before using this function or any other portions of the nifti.io package. This is necessary given the inconsistent way in which gzipped files are indexed (Some information on this is given in the documentation for the readBin function).
Values for t coordinates (coords[4]) may be Inf to retrieve all timepoints for the given x,y,z coordinates. If data is 4D and only x, y, z coordinates are given, the value at those coordinates for the first volume only is returned.
A number or a numeric vector containing values for all timepoints.
Timothy R. Koscik <[email protected]>
# get filename for example NII file included in nifti.io package nii.eg <- system.file("extdata", "egBrain.nii", package="nifti.io") # set coordinates (this is a voxel in the head of the # caudate in the right hemisphere in the example image) coordinates <- c(20,35,20,1) # read voxel value at coordinates voxel.value <- read.nii.voxel(nii.file = nii.eg, coords = coordinates)# get filename for example NII file included in nifti.io package nii.eg <- system.file("extdata", "egBrain.nii", package="nifti.io") # set coordinates (this is a voxel in the head of the # caudate in the right hemisphere in the example image) coordinates <- c(20,35,20,1) # read voxel value at coordinates voxel.value <- read.nii.voxel(nii.file = nii.eg, coords = coordinates)
Write Dataframe or Matrix to NII file
table.to.nii(in.table, coords, save.dir, prefix=NULL, do.log=TRUE, model.string=NULL, ref.nii=NULL, img.dims=NULL, pixdim=NULL, orient=NULL)table.to.nii(in.table, coords, save.dir, prefix=NULL, do.log=TRUE, model.string=NULL, ref.nii=NULL, img.dims=NULL, pixdim=NULL, orient=NULL)
in.table |
dataframe or matrix object to output to NII file |
coords |
voxel coordinates of location in NII file to write values |
save.dir |
directory location to save output |
prefix |
prefix to be the base of filenames, default is the name of the input table object |
do.log |
logical, whether or not to write log file providing details about what the output contents are. this may be helpful for sorting through volumes. |
model.string |
A string to wirte to the log file specifying describing or specifying the model that was run |
ref.nii |
a reference NII image to draw image properties from (e.g., dimensions and orientation) |
img.dims |
voxel dimensions of target NII file |
pixdim |
voxel dimensions of NII output |
orient |
orientation list object of NII output |
Output directly to log.text file and write to specified coordinates in a set of NII files.
Timothy R. Koscik <[email protected]>
# get filename for example NII file included in nifti.io package ref.nii <- system.file("extdata", "egBrain.nii", package="nifti.io") mdl <- lm(mpg ~ cyl, mtcars) mdl.coef <- as.data.frame(summary(mdl)$coef) table.to.nii(in.table=mdl.coef, coords=c(20,35,20), save.dir=tempdir(), prefix="exampleModel_coef", model.string="lm(mpg ~ cyl, mtcars)", ref.nii=ref.nii)# get filename for example NII file included in nifti.io package ref.nii <- system.file("extdata", "egBrain.nii", package="nifti.io") mdl <- lm(mpg ~ cyl, mtcars) mdl.coef <- as.data.frame(summary(mdl)$coef) table.to.nii(in.table=mdl.coef, coords=c(20,35,20), save.dir=tempdir(), prefix="exampleModel_coef", model.string="lm(mpg ~ cyl, mtcars)", ref.nii=ref.nii)
Write values to a specific volume in a NIfTI-1 file.
write.nii.volume(nii.file, vol.num, values)write.nii.volume(nii.file, vol.num, values)
nii.file |
Full directory listing to a NIfTI file. File must not be gzipped. |
vol.num |
An integer indicating which volume to read. |
values |
an array or vector of values to be written |
NIfTI files need to be unzipped before using this function or any other portions of the nifti.io package. This is necessary given the inconsistent way in which gzipped files are indexed.
Output directly to NIFTI file.
Timothy R. Koscik <[email protected]>
# get filename for example NII file included in nifti.io package ref.nii <- system.file("extdata", "egBrain.nii", package="nifti.io") # create a temporary file to write into tdir <- tempdir() new.nii <- paste0(tdir, "/new.nii") init.nii(new.nii = new.nii, ref.nii = ref.nii) # generate an array of random values the same size as the image volume xyz.dims <- info.nii(ref.nii, "xyz") new.values <- array(rnorm(prod(xyz.dims)), dim=xyz.dims) # write out volume all at once write.nii.volume(nii.file = new.nii, vol.num = 1, values = new.values)# get filename for example NII file included in nifti.io package ref.nii <- system.file("extdata", "egBrain.nii", package="nifti.io") # create a temporary file to write into tdir <- tempdir() new.nii <- paste0(tdir, "/new.nii") init.nii(new.nii = new.nii, ref.nii = ref.nii) # generate an array of random values the same size as the image volume xyz.dims <- info.nii(ref.nii, "xyz") new.values <- array(rnorm(prod(xyz.dims)), dim=xyz.dims) # write out volume all at once write.nii.volume(nii.file = new.nii, vol.num = 1, values = new.values)
Write NII Voxel
write.nii.voxel(nii.file, coords, value)write.nii.voxel(nii.file, coords, value)
nii.file |
Full directory listing to a NIfTI file. File must not be gzipped. |
coords |
A numeric vector conatining x,y,z,t coordinates indicating the location to write values |
value |
A numeric value to write |
NIfTI files need to be unzipped before using this function or any other portions of the nifti.io package. This is necessary given the inconsistent way in which gzipped files are indexed (Some information on this is given in the documentation for the readBin function).
Output directly to NIFTI file.
Timothy R. Koscik <[email protected]>
# get filename for example NII file included in nifti.io package ref.nii <- system.file("extdata", "egBrain.nii", package="nifti.io") # create a temporary file to write into tdir <- tempdir() new.nii <- paste0(tdir, "/new.nii") init.nii(new.nii = new.nii, ref.nii = ref.nii) # set coordinates and value of voxel to write coordinates <- c(20,35,20) new.value <- rnorm(1) # write to single voxel in NII file write.nii.voxel(nii.file = new.nii, coords = coordinates, value = new.value)# get filename for example NII file included in nifti.io package ref.nii <- system.file("extdata", "egBrain.nii", package="nifti.io") # create a temporary file to write into tdir <- tempdir() new.nii <- paste0(tdir, "/new.nii") init.nii(new.nii = new.nii, ref.nii = ref.nii) # set coordinates and value of voxel to write coordinates <- c(20,35,20) new.value <- rnorm(1) # write to single voxel in NII file write.nii.voxel(nii.file = new.nii, coords = coordinates, value = new.value)