Write a parcellation to a CIFTI-2 .dlabel file.

Write per-vertex label keys (one per vertex of the complete surface, per structure) to a CIFTI-2 dense label file. This is the inverse of read.fs.parcellation.cifti.

Usage

write.fs.parcellation.cifti(
  filepath,
  data,
  template = NULL,
  structure = NULL,
  label_table = NULL,
  map_name = NULL,
  metadata = NULL
)

Arguments

filepath

character string, the path of the file to write. The name should end with .dscalar.nii.

data

integer vector, matrix or named list, the label keys per vertex, see data in write.fs.morph.cifti. The values have to be the label keys of the label table (they are written as integers, and a key of 0 usually means unknown).

template

character string (the path of a CIFTI-2 file), an fs.cifti or an fs.cifti.data object, or NULL. The grayordinate mapping of this file is used, so pass the file the data comes from (e.g. an HCP file of the same subject): the mapping of such a file cannot be invented. Without a template, the file covers all vertices of the surfaces, and structure has to be given.

structure

character string or NULL, the brain structure the data belongs to (e.g. 'lh'), needed if data is not a named list and there is no template to take the structures from.

label_table

data.frame or NULL, the label table, see cifti.axis.labels: the columns 'key', 'red', 'green', 'blue', 'alpha' (in the range 0 to 1) and 'label'. The colortable of an fs.annot instance (see read.fs.annot) is accepted as well, its colors are then divided by 255. Without a label table the file still stores the keys, but nothing in it explains what they mean (Connectome Workbench writes one, and its label files rely on it).

map_name

character string or NULL, the name of the label map.

metadata

named character vector or NULL, the matrix metadata, see write.cifti. The default keeps the metadata of the template file.

Value

the axes that were written, invisibly.

See also

Other cifti functions: cifti.axis.brain.models(), cifti.axis.from.template(), cifti.axis.labels(), cifti.axis.parcels(), cifti.axis.parcels.from.annot(), cifti.axis.scalars(), cifti.axis.series(), cifti.brain.model.surface(), cifti.brain.model.volume(), cifti.dim.labels(), cifti.file.type.for.axes(), cifti.grayordinates(), cifti.header.from.axes(), cifti.label.table(), cifti.parcel(), cifti.parcels(), cifti.series.info(), cifti.structure.data(), cifti.structures(), cifti.volume(), print.fs.cifti(), print.fs.cifti.data(), print.fs.connectome(), read.cifti(), read.cifti.header(), read.cifti.rows(), read.fs.connectome.cifti(), write.cifti(), write.fs.connectome.cifti(), write.fs.morph.cifti(), write.fs.parcellated.cifti(), write.fs.series.cifti()

Examples

template <- system.file("extdata", "cifti", "tiny.dlabel.nii", package = "freesurferformats")
keys <- read.fs.parcellation.cifti(template, "lh")
label_table <- read.fs.parcellation.cifti(template, "lh", with_label_table = TRUE)$label_table
out_file <- file.path(tempdir(), "written.dlabel.nii")
write.fs.parcellation.cifti(out_file, keys, template = template, structure = "lh",
                            label_table = label_table)
table(read.fs.parcellation.cifti(out_file, "lh"))
#> 
#> 0 1 2 3 
#> 1 3 3 3