ciftiTools (version 0.9.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
)
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
)
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
)

Arguments

cifti_fname

File path to a CIFTI file (ending in ".d*.nii").

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.

cortexL_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".

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

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

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

(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".

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.

Value

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

Connectome Workbench

This function interfaces with the "-cifti-separate" Workbench command.

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.

See Also

Other functions for writing CIFTI or GIFTI data: write_cifti(), write_metric_gifti(), write_subcort_nifti(), write_surf_gifti()