0th

Percentile

##### Read a CIFTI file with optional resampling

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.

Keywords
internal
##### Usage
read_cifti_separate(
cifti_fname,
surfL_fname = NULL,
surfR_fname = NULL,
brainstructures = c("left", "right"),
resamp_res = NULL,
sep_keep = FALSE,
sep_fnames = NULL,
resamp_keep = FALSE,
resamp_fnames = NULL,
write_dir = NULL,
mwall_values = c(NA, NaN),
wb_path = NULL,
verbose = TRUE
)
##### Arguments
cifti_fname

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

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

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

sep_keep

If separated files are created, should they be kept or deleted at the end of this function call? Default: FALSE (delete). Keeping the separated files may help speed up certain tasks, for example when repeatedly iterating over subjects--the CIFTI will only be separated once instead of at each iteration.

sep_fnames

(Optional) Where to write the separated files (override their default file names). This is a named list where each entry's name is a file type label, and each entry's value is a file name indicating where to write the corresponding separated file. The recognized file type labels are: "cortexL", "cortexR", "ROIcortexL", "ROIcortexR", "subcortVol", and "subcortLabs".

Entry values can be NULL, in which case a default file name will be used: see cifti_component_suffix. Default file names will also be used for files that need to be separated/written but without a corresponding entry in sep_fnames.

Entries in sep_fnames will be ignored if they are not needed based on [ROI_]brainstructures. For example, if brainstructures="left", then sep_fnames$cortexR will be ignored if specified. The write_dir argument can be used to place each separated file in the same directory. resamp_keep If resampled files are created, will they be kept or deleted at the end of this function call? Default: FALSE (delete). Keeping the resampled files may help speed up certain tasks, for example when repeatedly iterating over CIFTI files--resampling will only be done once instead of every new iteration. resamp_fnames Where to write the resampled files. This is a named list where each entry's name is a file type label, and each entry's value is a file name indicating where to write the corresponding resampled file. The recognized file type labels are: "cortexL", "cortexR", "ROIcortexL", "ROIcortexR", "validROIcortexL", and "validROIcortexR". Entry values can be NULL, in which case a default file name will be used: see resample_cifti_default_fname. Default file names will also be used for files that need to be resampled/written but without a corresponding entry in resamp_fnames. Entries in resamp_fnames will be ignored if they are not needed based on [ROI_]brainstructures. For example, if brainstructures="left", then resamp_fnames$cortexR will be ignored if specified.

The write_dir argument can be used to place each resampled file in the same directory.

write_dir

Where should any output files be written? NULL (default) will write them to the current working directory.

Files flagged for deletion will be written to a temporary directory, and thus are not affected by this argument. So if sep_keep is TRUE, the separated files will be written to write_dir, but if sep_keep is FALSE, they will be written to tempdir() and later deleted. resamp_keep works similarly.

For read_cifti_separate, the surface files (surfL or surfR) are deleted if resamp_keep is FALSE, so in this case they will be written to tempdir(). But for resample_cifti, the surface files are kept even if resamp_keep is FALSE, so they will always be written to write_dir.

Different subfolders for the separated, resampled, and final output files cannot be specified by write_dir. Instead, modify the individual file names in sep_fnames and resamp_fnames.

write_dir must already exist, or an error will occur.

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

##### Details

The subcortical component (NIFTI) is not resampled.

##### Value

A "xifti" object. See is.xifti.

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