| Type: | Package |
| Title: | Read and Write NIfTI Files |
| Version: | 1.0.0 |
| Author: | Timothy R. Koscik [aut, cre, cph] |
| Maintainer: | Timothy Koscik <timothy-koscik@uiowa.edu> |
| Depends: | R (≥ 3.5.0) |
| 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. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| NeedsCompilation: | no |
| Packaged: | 2021-06-07 14:03:28 UTC; Tim |
| Repository: | CRAN |
| Date/Publication: | 2021-06-08 07:30:02 UTC |
Retrieve NIfTI Header Information
Description
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.
Usage
info.nii(nii.file, field="hdr")Arguments
nii.file |
Full directory listing to NIfTI file. |
field |
A character vector of field names to be returned. |
Details
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'
Value
A vector or named list containing the requested output
Author(s)
Timothy R. Koscik <timothy-koscik@uiowa.edu>
Examples
# 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")
Initialize Empty NIfTI File
Description
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
Usage
init.nii(new.nii,
ref.nii=NULL,
dims,
pixdim=NULL,
orient=NULL,
datatype=16,
init.value=NA)
Arguments
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 |
Value
No return value
Author(s)
Timothy R. Koscik <timothy-koscik@uiowa.edu>
Examples
# 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 NII Volume
Description
Read indicated volume from NIfTI files.
Usage
read.nii.volume(nii.file, vol.num)
Arguments
nii.file |
Full directory listing to a NIFTI file. File must not be gzipped. |
vol.num |
An integer indicating which volume to read. |
Details
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).
Value
An array containing values from NIFTI volume.
Author(s)
Timothy R. Koscik <timothy-koscik@uiowa.edu>
Examples
# 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 NII Voxel
Description
Read values from NIfTI files at given coordinates (x,y,z,t).
Usage
read.nii.voxel(nii.file, coords)
Arguments
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). |
Details
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.
Value
A number or a numeric vector containing values for all timepoints.
Author(s)
Timothy R. Koscik <timothy-koscik@uiowa.edu>
Examples
# 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)
Table to NII file
Description
Write Dataframe or Matrix to NII file
Usage
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)
Arguments
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 |
Value
Output directly to log.text file and write to specified coordinates in a set of NII files.
Author(s)
Timothy R. Koscik <timothy-koscik@uiowa.edu>
Examples
# 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 NIfTI-1 Volume
Description
Write values to a specific volume in a NIfTI-1 file.
Usage
write.nii.volume(nii.file, vol.num, values)
Arguments
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 |
Details
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.
Value
Output directly to NIFTI file.
Author(s)
Timothy R. Koscik <timothy-koscik@uiowa.edu>
Examples
# 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
Description
Write NII Voxel
Usage
write.nii.voxel(nii.file, coords, value)
Arguments
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 |
Details
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).
Value
Output directly to NIFTI file.
Author(s)
Timothy R. Koscik <timothy-koscik@uiowa.edu>
Examples
# 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)