Read surface parcellation data from CIFTI dlabel files.

Read the data from a CIFTI dlabel file (a dense surface parcellation, i.e., an integer label key per vertex) and return the per-vertex label keys for a single brain structure. This is the CIFTI analogue of a FreeSurfer annotation file.

Usage

read.fs.parcellation.cifti(
  filepath,
  brain_structure = "CIFTI_STRUCTURE_CORTEX_LEFT",
  data_column = 1L,
  with_label_table = FALSE
)

Arguments

filepath

character string, the full path to a file in CIFTI 2 format, should end with '.dlabel.nii'. Note that this is NOT a NIfTI file, despite the '.nii' part; it uses a CIFTI 2 header instead. See the spec for details. An 'fs.cifti' object from read.cifti.header or an 'fs.cifti.data' object from read.cifti may be given instead of a path (this is faster if you need the data of several structures). An object created by the 'cifti' package is still accepted for backwards compatibility.

brain_structure

character string or integer, the brain structure for which the data should be extracted from the file. Can be a CIFTI brain structure string (one of 'CIFTI_STRUCTURE_CORTEX_LEFT' or 'CIFTI_STRUCTURE_CORTEX_RIGHT'), or simply one of 'lh', 'rh' (which are used as aliases for the former). If you specify 'both', the concatenated data for 'lh' (first) and 'rh' will be returned, but you will get no information on hemi boundaries. If it is an integer, it will be interpreted as an index into the list of structures within the CIFTI file, use with care.

data_column

integer, the data column (map) to return. A CIFTI dlabel file can contain several parcellations in different columns in a single file; this selects which one. The columns are not named, so you will need to know this in advance if the file has several maps (you can use the 'with_label_table' option to inspect the map names).

with_label_table

logical, whether to also return the label table (the mapping from label key to region name and RGBA color) for the selected map. If 'TRUE', the return value is a list, see the Value section.

Value

If 'with_label_table' is 'FALSE' (the default), an integer vector with one label key per vertex in the surface. Vertices which did not have a value in the CIFTI data are set to NA; a key of 0 denotes the unknown / medial wall label (see the label table). If 'with_label_table' is 'TRUE', a named list with entries: 'label_keys' (the integer vector), 'label_table' (a data.frame with columns 'Key', 'Red', 'Green', 'Blue', 'Alpha' and 'Label', where the RGBA values are in the range 0 to 1), 'map_name' (the name of the selected map as a character string, or 'NULL' if unnamed), and 'brain_structure' (a character string). If 'brain_structure' is 'both' and 'with_label_table' is 'TRUE', a named list with entries 'lh' and 'rh', each as described above.

References

See https://www.nitrc.org/forum/attachment.php?attachid=341&group_id=454&forum_id=1955 for the CIFTI 2 file format spec. See https://www.nitrc.org/projects/cifti/ for more details on CIFTI, including example files.

Examples

label_file <- system.file("extdata", "cifti", "tiny.dlabel.nii", package = "freesurferformats")
parc_lh <- read.fs.parcellation.cifti(label_file, "lh")
table(parc_lh)
#> parc_lh
#> 0 1 2 3 
#> 1 3 3 3 
parc_with_table <- read.fs.parcellation.cifti(label_file, "lh", with_label_table = TRUE)
parc_with_table$label_table
#>   Key Red Green Blue Alpha    Label
#> 1   0   1   1.0    1     0      ???
#> 2   1   0   0.5    1     1 PARCEL_A
#> 3   2   0   0.5    1     1 PARCEL_B
#> 4   3   0   0.5    1     1 PARCEL_C