read_cifti_separate

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

Aliases
  • read_cifti_separate
Documentation reproduced from package ciftiTools, version 0.1.6.0, License: GPL-3

Community examples

Looks like there are no examples yet.