read_cifti: Read a CIFTI file

Description

Read a CIFTI file as a "xifti" object (see is.xifti).

Usage

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

Arguments

cifti_fname

File path of CIFTI-format data (ending in ".d*.nii").

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$ greyordinates 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 greyordinates 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.

surfL_fname

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

surfR_fname

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

brainstructures

Character vector indicating which brain structure(s) to obtain: "left" (left cortical surface), "right" (right cortical surface) and/or "subcortical" (subcortical and cerebellar gray matter). Can also be "all" (obtain all three brain structures). Default: c("left","right") (cortical surface only).

If a brain structure is indicated but does not exist, a warning will be raised and that brain structure will be skipped.

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.

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.

wb_path

(Optional) Path to Connectome Workbench folder or executable. If not provided, should be set with ciftiTools.setOption("wb_path", "path/to/workbench").

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$ greyordinates).

Connectome Workbench Requirement

This function uses a system wrapper for the 'wb_command' executable. The user must first download and install the Connectome Workbench, available from https://www.humanconnectome.org/software/get-connectome-workbench . The wb_path argument is the full file path to the Connectome Workbench folder. (The full file path to the 'wb_cmd' executable also works.)

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.

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 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.