read_cifti_separate: Read a CIFTI file with optional resampling

Description

Read a CIFTI file by writing each component into a GIFTI and NIFTI file (separate_cifti), optionally resampling the GIFTIs, (resample_gifti), and then reading each separated component into R (make_xifti). Surfaces can also be provided; they will be resampled along with the CIFTI for viewing.

Usage

read_cifti_separate(
  cifti_fname,
  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,
  mwall_values = c(NA, NaN),
  verbose = TRUE
)

Value

A "xifti" object. See is.xifti.

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

(Optional) Target resolution for resampling (number of cortical surface vertices per hemisphere). If NULL (default) or FALSE, do not perform resampling.

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.

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

Details

The subcortical component (NIFTI) is not resampled.