resample_cifti: Resample CIFTI Data

Description

Performs spatial resampling of CIFTI data on the cortical surface by separating it into GIFTI and NIFTI files, resampling the GIFTIs, and then putting them together. (The subcortex is not resampled.)

Usage

resample_cifti(
  cifti_original_fname,
  cifti_target_fname,
  surfL_original_fname = NULL,
  surfR_original_fname = NULL,
  surfL_target_fname = NULL,
  surfR_target_fname = NULL,
  resamp_res,
  sep_keep = FALSE,
  sep_fnames = NULL,
  resamp_keep = FALSE,
  resamp_fnames = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE,
  wb_path = NULL
)
resampleCIfTI(
  cifti_original_fname,
  cifti_target_fname,
  surfL_original_fname = NULL,
  surfR_original_fname = NULL,
  surfL_target_fname = NULL,
  surfR_target_fname = NULL,
  resamp_res,
  sep_keep = FALSE,
  sep_fnames = NULL,
  resamp_keep = FALSE,
  resamp_fnames = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE,
  wb_path = NULL
)
resamplecii(
  cifti_original_fname,
  cifti_target_fname,
  surfL_original_fname = NULL,
  surfR_original_fname = NULL,
  surfL_target_fname = NULL,
  surfR_target_fname = NULL,
  resamp_res,
  sep_keep = FALSE,
  sep_fnames = NULL,
  resamp_keep = FALSE,
  resamp_fnames = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE,
  wb_path = NULL
)
resample_xifti(
  cifti_original_fname,
  cifti_target_fname,
  surfL_original_fname = NULL,
  surfR_original_fname = NULL,
  surfL_target_fname = NULL,
  surfR_target_fname = NULL,
  resamp_res,
  sep_keep = FALSE,
  sep_fnames = NULL,
  resamp_keep = FALSE,
  resamp_fnames = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE,
  wb_path = NULL
)

Arguments

cifti_original_fname

A CIFTI file to resample.

cifti_target_fname

The file name to save the resampled CIFTI.

surfL_original_fname, surfR_original_fname

(Optional) File path of existing GIFTI surface geometry file representing the left/right cortex. One or both can be provided. These will be resampled too, and are convenient for visualizing the resampled data.

surfL_target_fname, surfR_target_fname

(Optional) File path for the resampled GIFTI surface geometry file representing the left/right cortex. If NULL (default), will use default names: see resample_cifti_default_fname.

resamp_res

Target resolution for resampling (number of cortical surface vertices per hemisphere).

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.

Correctly indicating the medial wall locations is important for resampling, because the medial wall mask is taken into account during resampling calculations.

verbose

Should occasional updates be printed? Default: TRUE.

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 of written files: "cifti" and potentially "surfL" (if surfL_original_fname was provided) and/or "surfR" (if surfR_original_fname was provided).

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