read_cifti: Read a CIFTI file

Description

Read in a CIFTI file as a "xifti" object.

Usage

read_cifti(
  cifti_fname = NULL,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = c("left", "right"),
  idx = NULL,
  resamp_res = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)
readCIfTI(
  cifti_fname = NULL,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = c("left", "right"),
  idx = NULL,
  resamp_res = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)
readcii(
  cifti_fname = NULL,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = c("left", "right"),
  idx = NULL,
  resamp_res = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)
read_xifti(
  cifti_fname = NULL,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = c("left", "right"),
  idx = NULL,
  resamp_res = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)

Arguments

cifti_fname

File path to a CIFTI file (ending in ".d*.nii").

surfL_fname

(Optional) File path to a GIFTI surface geometry file representing the left cortex.

surfR_fname

(Optional) File path to a GIFTI surface geometry file representing the right cortex.

brainstructures

Character vector indicating which brain structure(s) to obtain: "left" (left cortex), "right" (right cortex) and/or "subcortical" (subcortex and cerebellum). Can also be "all" (obtain all three brain structures). Default: c("left","right") (cortex only).

If a brain structure is indicated but does not exist in the CIFTI file, a warning will occur and that brain structure will be skipped.

idx

Numeric vector indicating the data indices (columns) to read. If NULL (default), read in all the data. Must be a subset of the indices present in the file, or an error will occur.

For high-resolution CIFTI files, reading in only a subset of the data saves memory, but will be slower than reading in the entire file due to the required intermediate steps.

resamp_res

Resolution to resample the cortical data and surface to. Default: NULL (do not resample). If not NULL, the data will have to be read in with -cifti-separate, which is slower than -cifti-convert -to-gifti-ext.

flat

Should the result be flattened into a single matrix?

If FALSE (default), the result will be a "xifti" object.

If TRUE, the result will be a $T x G$ matrix ($T$ measurements, $G$ grayordinates not including the medial wall if it's excluded from the ROI). All below arguments will be ignored because the brain structures cannot be identified. Surfaces will not be appended. Resampling is also not possible. flat==TRUE is the fastest way to read in just the CIFTI data.

If TRUE, the grayordinates will be ordered by left cortex, right cortex, and then subcortex. Subcortical voxels will be ordered by alphabetical label. However, where each brainstructure (and subcortical structure) begins and ends cannot be determined. The medial wall locations and subcortical brain mask are also not included. The data matrix will be identical to that created by -cifti-convert -to-gifti-ext.

mwall_values

If the medial wall locations are not indicated in the CIFTI, use these values to infer the medial wall mask. Default: c(NA, NaN). If NULL, do not attempt to infer the medial wall.

verbose

Should occasional updates be printed? Default: FALSE.

...

Additional arguments to read_cifti_convert or read_cifti_separate.

Value

If !flat, a "xifti" object. Otherwise, a $T x G$ matrix ($T$ measurements, $G$ grayordinates).

Connectome Workbench

This function interfaces with the "-cifti-convert" Workbench command if resampling is not needed, and the "-cifti-separate" Workbench command if resampling is needed.

Label Levels

xifti$meta$subcort$labels is a factor with the following levels:

Cortex-L
Cortex-R
Accumbens-L
Accumbens-R
Amygdala-L
Amygdala-R
Brain Stem
Caudate-L
Caudate-R
Cerebellum-L
Cerebellum-R
Diencephalon-L
Diencephalon-R
Hippocampus-L
Hippocampus-R
Pallidum-L
Pallidum-R
Putamen-L
Putamen-R
Thalamus-L
Thalamus-R

These correspond to the same structures as given by ft_read_cifti in the cifti-matlab MATLAB toolbox. Note that the first two levels (left and right cortex) are not used.

Details

First, metadata is obtained with info_cifti. Then, if no resampling is requested, the -cifti-convert -to-gifti-ext Workbench Command is used to "flatten" the data and save it as a metric or label GIFTI file, which is read in and separated by brainstructure according to the metadata (read_cifti_convert). Otherwise, if sampling is requested, then the CIFTI is separated into its GIFTI and NIFTI components, resampled, and then re-assembled (read_cifti_separate). The former is much faster for large CIFTI files, so the latter is only used when necessary for resampling.

If cifti_fname is not provided, then only the surfaces are read in.