R: Read a CIFTI file

read_cifti {ciftiTools}

R Documentation

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,
  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 = c("left", "right"),
  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 = c("left", "right"),
  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 = c("left", "right"),
  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,
  ...
)

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

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.

Value

If !flat, a "xifti" object. Otherwise, a T \times 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.