make_subcort: Make the subcortical components of a `"xifti"`

Description

Coerce subcortical data into valid entries for xifti$data$subcort and xifti$meta$subcort. The data arguments can be matrices/arrays or NIFTI file paths. If the mask is not provided, it will be inferred from the labels.

Usage

make_subcort(vol, labs, mask = NULL, idx = NULL, validate_mask = FALSE)

Value

A list with components "data", "labels", "mask", and "trans_mat". The first two will be vectorized and ordered spatially.

The volume can be recovered using: vol <- unvec_vol(data, mask, fill=NA)

labs <- unvec_vol(labels, mask, fill=0)

Arguments

vol: represents the data values of the subcortex. It is either a NIFTI file path, 3D/4D data array ($i \times j \times k \times T$), or a vectorized data matrix ($V_S$ voxels by $T$ measurements). If it's vectorized, the voxels should be in spatial order.
labs: represents the brainstructure labels of each voxel: see substructure_table. It is either a NIFTI file path, a 3D data array ($i \times j \times k$) of numeric 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 (2 and 3 correspond to left and right cortex, respectively) or 1-19 (cortex labels omitted), with 0 representing out-of-mask voxels.
mask: is a NIFTI file path or logical 3D data array ($i \times j \times k$) where TRUE values indicate subcortical voxels (in-mask). If it is not provided, the mask will be inferred from voxels with labels 0 or NA in subcortLabs. If subcortLabs are vectorized and subcortMask is not provided, the mask cannot be inferred so an error will occur.
idx: Only applies if vol is a NIFTI file path. This is a numeric vector indicating the data indices to read. If NULL (default), read all the data. Must be a subset of the indices present in the file, or an error will occur.
validate_mask: If mask is provided, set this to TRUE to check that the mask only removes voxels with NA and 0 values in vol and labs. Default: FALSE (saves time).

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. Note that the first two levels (left and right cortex) are not used.

Details

To read in the labels as the primary data, use the labels NIFTI for both vol and labs.