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.
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
)File path of CIFTI-format data (ending in ".d*.nii").
(Optional) File path of GIFTI surface geometry file representing the left cortex.
(Optional) File path of GIFTI surface geometry file representing the right cortex.
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.
(Optional) Target resolution for resampling (number of
cortical surface vertices per hemisphere). If NULL (default) or
FALSE, do not perform resampling.
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.
(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.
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.
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.
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.
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.
(Optional) Path to Connectome Workbench folder or executable.
If not provided, should be set with
ciftiTools.setOption("wb_path", "path/to/workbench").
Should occasional updates be printed? Default: TRUE.
A "xifti" object. See is.xifti.
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.)
The subcortical component (NIFTI) is not resampled.