ciftiTools (version 0.1.6.0)

separate_cifti: Separate a CIFTI file

Description

Separate a CIFTI file into GIFTI files for the cortical data and NIFTI files for the subcortical data and labels. ROIs can also be written to indicate the medial wall mask (cortex) and volume mask (subcortex). This uses the Connectome Workbench command -cifti-separate.

Usage

separate_cifti(
  cifti_fname,
  brainstructures = c("left", "right"),
  cortexL_fname = NULL,
  cortexR_fname = NULL,
  subcortVol_fname = NULL,
  subcortLabs_fname = NULL,
  ROI_brainstructures = "all",
  ROIcortexL_fname = NULL,
  ROIcortexR_fname = NULL,
  ROIsubcortVol_fname = NULL,
  write_dir = NULL,
  wb_path = NULL
)

separateCIfTI( cifti_fname, brainstructures = c("left", "right"), cortexL_fname = NULL, cortexR_fname = NULL, subcortVol_fname = NULL, subcortLabs_fname = NULL, ROI_brainstructures = "all", ROIcortexL_fname = NULL, ROIcortexR_fname = NULL, ROIsubcortVol_fname = NULL, write_dir = NULL, wb_path = NULL )

separatecii( cifti_fname, brainstructures = c("left", "right"), cortexL_fname = NULL, cortexR_fname = NULL, subcortVol_fname = NULL, subcortLabs_fname = NULL, ROI_brainstructures = "all", ROIcortexL_fname = NULL, ROIcortexR_fname = NULL, ROIsubcortVol_fname = NULL, write_dir = NULL, wb_path = NULL )

Arguments

cifti_fname

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

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.

cortexL_fname, cortexR_fname

(Optional) GIFTI file names (*.[func/label].gii) to save the [left/right] cortex data to. If not provided, defaults to "*[L/R].[func/label].gii", where * is the file name component of cifti_fname. Will be written in write_dir.

dtseries and dscalar files should use "func", whereas dlabel files should use "label".

subcortVol_fname, subcortLabs_fname

(Optional) NIFTI file names to save the subcortical [volume/labels] to. If not provided, defaults to "*[/.labels].nii", where * is the file name component of cifti_fname. Will be written in write_dir.

ROI_brainstructures

Which ROIs should be obtained? "all" (default) to obtain ROIs for each of the brainstructures. NULL to not obtain any ROIs. This should be a subset of brainstructures.

ROIcortexL_fname, ROIcortexR_fname

(Optional) GIFTI file names (*.[func/label].gii) to save the [left/right] cortex ROI to. If not provided, defaults to "*ROI_[L/R].[func/label].gii", where * is the file name component of cifti_fname. The cortical ROIs typically represent the medial wall mask, with values of 1 for in-ROI (non-medial wall) vertices and 0 for out-of-ROI (medial wall) vertices. Will be written in write_dir.

dtseries and dscalar files should use "func", whereas dlabel files should use "label".

ROIsubcortVol_fname

(Optional) NIFTI file names to save the subcortical ROI to. If not provided, defaults to "*ROI.nii", where * is the file name component of cifti_fname. The subcortical ROI typically represents the volumetric mask for the entire subcortical structure, with values of 1 for in-ROI (in subcortex) voxels and 0 for out-of-ROI (not in subcortex) voxels. Will be written in write_dir.

write_dir

Where should the separated files be placed? NULL (default) will write them to the current working directory.

write_dir must already exist, or an error will occur.

wb_path

(Optional) Path to Connectome Workbench folder or executable. If not provided, should be set with ciftiTools.setOption("wb_path", "path/to/workbench").

Value

A named character vector with the file paths to the written NIFTI and GIFTI files

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

Details

Time unit, start, and step (dtseries files) will not be written to the GIFTI/NIFTIs. Column names (dscalar files) will not be written to the GIFTIs, as well as label names and colors (dlabel files). (Haven't checked the NIFTIs yet.)

ROI/medial wall behavior: If there are 32k vertices in the left cortex with 3k representing the medial wall, then both cortexL_fname and ROIcortexL_fname will have 32k entries, 3k of which having a value of 0 indicating the medial wall. The non-medial wall entries will have the data values in cortexL_fname and a value of 1 in ROIcortexL_fname. Thus, exporting ROIcortexL_fname is vital if the data values include 0, because 0-valued non-medial wall vertices and medial wall vertices cannot be distinguished from one another within cortexL_fname alone.