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 = "existing",
  idx = NULL,
  resamp_res = NULL,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)
readCIfTI(
  cifti_fname = NULL,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = "existing",
  idx = NULL,
  resamp_res = NULL,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)
readcii(
  cifti_fname = NULL,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = "existing",
  idx = NULL,
  resamp_res = NULL,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)
read_xifti(
  cifti_fname = NULL,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = "existing",
  idx = NULL,
  resamp_res = NULL,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)

Value

If !flat, a "xifti" object. Otherwise, a $T \times G$

matrix ($T$ measurements, $G$ grayordinates).

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 read in: "left" (left cortex), "right" (right cortex) and/or "subcortical" (subcortex and cerebellum). Can also be "all" (read all three brain structures), or "existing" (read all brain structures in the file). Default: "existing".

If a brain structure is indicated but does not exist, a warning will be raised 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.

resamp_method

"barycentric" (default) or "adaptive" resampling for the metric or label data. These options correspond to the Workbench command options "BARYCENTRIC" and "ADAP_BARY_AREA", respectively.

While adaptive resampling is recommended for metric or label data, it requires that area[L/R]_original_fname be provided.

Note that surfaces will resampled using barycentric resampling regardless of resamp_method, because barycentric resampling rather than adaptive resampling is recommended for surface data.

areaL_original_fname, areaR_original_fname

File paths to the surfaces to use for vertex area correction during adaptive resampling. (Only used if resampling with the adaptive method.) area[L/R]_original_fname should match the current resolution of the data.

For resampling: the Workbench command for adaptive resampling requires the target surfaces for area correction too. But to make the workflow easier, ciftiTools will resample area[L/R]_original_fname with the barycentric method and use that for the target area.

For remapping: area[L/R]_target_fname must be directly provided.

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

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.