make_xifti: Assemble a `"xifti"` object

Description

Assembles cortical data, subcortical data, and/or surface geometry to form a "xifti" object. The inputs can be file paths, GIFTI or NIFTI files which have been read in, or data objects (vectors, matrices or arrays, depending on the argument). See as.xifti for a user-function wrapper that only works with data objects. make_xifti can be used to combine the files written by separate_cifti, or read individual components independent of any CIFTI file.

Usage

make_xifti(
  cortexL = NULL,
  cortexL_mwall = NULL,
  cortexR = NULL,
  cortexR_mwall = NULL,
  subcortVol = NULL,
  subcortLabs = NULL,
  subcortMask = NULL,
  mwall_values = c(NA, NaN),
  cifti_info = NULL,
  surfL = NULL,
  surfR = NULL,
  col_names = NULL,
  HCP_32k_auto_mwall = TRUE,
  read_dir = NULL
)

Arguments

cortexL, cortexL_mwall

Left cortex data and ROI. Each must be a path to a GIFTI file, metric "gifti" object, data matrix or vector.

If cortexL_mwall is not provided, cortexL should have data for all vertices on the left cortical surface ($V_L x T$ data matrix). There will not be a mask for the medial wall. Not providing the medial wall mask is appropriate for ".dlabels.nii" files where the medial wall may have its own label and therefore should not be treated as missing data.

If cortexL_mwall is provided, cortexL should either have data for all vertices on the left cortical surface ($V_L x T$ data matrix, with filler values e.g. 0 or NaN for medial wall vertices), or have data only for non-medial wall vertices ($(V_L - mwall_L) x T$ data matrix). The medial wall mask will be the 0 values in cortexL_mwall. The medial wall mask should be provided whenever the medial wall should be treated as missing data.

Since the unmasked cortices must have the same number of vertices, V_L should match V_R.

cortexR, cortexR_mwall

Right cortex data and ROI. Each must be a path to a GIFTI file, metric "gifti" object, data matrix or vector.

If cortexR_mwall is not provided, cortexR should have data for all vertices on the right cortical surface ($V_R x T$ data mre will not be a mask for the medial wall. Not providing the medial wall mask is appropriate for ".dlabels.nii" files where the medial wall may have its own label and therefore should not be treated as missing data.

If cortexR_mwall is provided, cortexR should either have data for all vertices on the right cortical surface ($V_R x T$ data matrix, with filler values e.g. 0 or NaN for medial wall vertices), or have data only for non-medial wall vertices ($(V_R - mwall_R) x T$ data matrix). The medial wall mask will be the 0 values in cortexR_mwall. The medial wall mask should be provided whenever the medial wall should be treated as missing data.

Since the unmasked cortices must have the same number of vertices, V_L should match V_R.

subcortVol, subcortLabs, subcortMask

subcortVol represents the data values of the subcortex. It is either a NIFTI file path, 3D/4D data array ($i x j x k x T$), or a vectorized data matrix ($V_S$ voxels by $T$ measurements). If it's vectorized, the voxels should be in spatial order ($i$ index increasing fastest, then $j$, then $k$).

subcortLabs represents the brainstructure labels of each voxel: see substructure_table. It is either a NIFTI file path, 3D data array ($i x j x k$) of integer brainstructure indices, or a $V_S$ length vector in spatial order with brainstructure names as factors or integer indices. The indices should be 3-21 (1 and 2 correspond to left and right cortex, respectively) or 1-19 (cortex labels omitted), with 0 representing out-of-mask voxels.

subcortMask is NIFTI file path or logical 3D data array ($i x j x k$) where TRUE values indicate subcortical voxels (in-mask). If it is not provided, the mask will be inferred from voxels with labels 0, NA, or NaN in subcortLabs. If subcortLabs are vectorized and subcortMask is not provided, the mask cannot be inferred so an error will occur.

mwall_values

If cortex[L/R]_mwall was not provided, or if it was invalid (i.e. bad length or all TRUE), the medial wall mask will be inferred from rows in cortex[L/R] that are constantly one of these values. Default: c(NA, NaN). If NULL, do not attempt to infer the medial wall from the data values. NULL should be used if NA or NaN are legitimate values that non-medial wall vertices might take on.

cifti_info

(Optional) The result of info_cifti. If GIFTI and/or NIFTI components from a CIFTI are being provided, providing cifti_info gives metadata information that would otherwise have to be inferred: the NIFTI intent, brainstructures present in the original file, and miscellaneous metadata.

This argument is probably not necessary for end users: reading a CIFTI should be done by providing cifti_fname, and for reading separate GIFTI/NIFTI components cifti_info is not applicable.

surfL, surfR

(Optional) Surface geometries for the left or right cortex. Can be a surface GIFTI file path or "surf" object; see make_surf for a full description of valid inputs.

col_names

Names of each measurement/column in the data. Overrides names indicated in cifti_info or in the data components.

HCP_32k_auto_mwall

If left and/or right cortex data is provided, and the number of vertices matches that of the HCP 32k mesh (29696 on left, and 29716 on right), should the medial wall masks be added to the "xifti" if not provided? Default: TRUE.

read_dir

(Optional) Append a directory to all file names in the arguments. If NULL (default), do not modify file names.

Value

A "xifti" object; see template_xifti

Label Levels

xifti$meta$subcort$labels is a factor with the following levels:

Cortex-L
Cortex-R
Accumbens-L
Accumbens-R
Amygdala-L
Amygdala-R
Brain Stem
Caudate-L
Caudate-R
Cerebellum-L
Cerebellum-R
Diencephalon-L
Diencephalon-R
Hippocampus-L
Hippocampus-R
Pallidum-L
Pallidum-R
Putamen-L
Putamen-R
Thalamus-L
Thalamus-R

These correspond to the same structures as given by ft_read_cifti in the cifti-matlab MATLAB toolbox.

Details

Each data or surface component is optional. Metadata components (cortex[L/R]_mwall, subcortLabs, and subcortMask) will be ignored if its corresponding data component is not provided. If no data or surface components are provided, then the template_xifti will be returned.

If cortical data are provided without a corresponding medial wall mask, or if the provided mask is invalid or empty, then the medial wall will be inferred from data rows that are constantly a value in mwall_values. But if mwall_values is NULL, no attempt to infer the medial wall will be made and the medial wall metadata entry will be NULL.

The total number of greyordinates will be $G = (V_L - mwall_L) + (V_R - mwall_R) + V_S$: $V_L - mwall_L$ left vertices, $V_R - mwall_R$ right vertices and $V_S$ subcortical voxels. $T$, the total number of measurements (columns of data), must be the same for each brainstructure.