Create a CIFTI-2 parcels axis from brain surface annotations.

A parcellated CIFTI-2 file stores no label table, it describes each parcel by its name and by the vertices (per brain structure) and volume voxels it contains. This function builds such a parcels axis from brain surface annotations (see read.fs.annot), which assign a region label to every vertex of a hemisphere, so that data that was computed per region of an atlas (a FreeSurfer parcellation, a Schaefer atlas, ...) can be written to a parcellated file.

The vertices of a parcel are collected by the name of the region, not by its label key: the hemispheres of an atlas usually use the same names for the same region, but the names often carry a hemisphere marker (e.g. L_superiorfrontal in one hemisphere and R_superiorfrontal in the other, or 7Networks_LH_Vis_1 and 7Networks_RH_Vis_1), and a parcel of a parcellated CIFTI-2 file is a region that spans the structures it occurs in. The markers are removed before the names are compared, see cifti.region.name.without.hemisphere for the exact rules. Vertices whose label is not in the label table of the annotation (the medial wall, which is usually the 'unknown' region with key 0) form a parcel like any other, named default_label_name: a parcellated file has no 'no value' case, and dropping the medial wall silently would change the data.

Usage

cifti.axis.parcels.from.annot(
  annots,
  structure = NULL,
  parcel_names = NULL,
  default_label_name = "unknown"
)

Arguments

annots

an fs.annot instance (see read.fs.annot), or a named list of them, with the brain structures as the names (e.g. list(lh = lh_annot, rh = rh_annot)).

structure

character string or NULL, the brain structure of the annotation, needed if annots is a single fs.annot instance instead of a named list.

parcel_names

character vector or NULL, the names of the parcels to write, in that order. This selects and orders the parcels of the axis; without it all regions of the parcellation are used, in the order in which the label table of the annotation lists them (the atlas order, not the order in which the vertices happen to be stored in the mesh). Renaming is not supported, since the name is what the hemispheres of a region are matched by.

default_label_name

character string, the name to use for vertices whose label is not in the label table of the annotation.

Value

an axis of type 'CIFTI_INDEX_TYPE_PARCELS', see cifti.axis.parcels, to be passed to write.cifti or to one of the writers that accept it (e.g. write.fs.parcellated.cifti).

See also

Other cifti functions: cifti.axis.brain.models(), cifti.axis.from.template(), cifti.axis.labels(), cifti.axis.parcels(), 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.parcellation.cifti(), write.fs.series.cifti()

Examples

lh_annot_file <- system.file("extdata", "lh.aparc.annot.gz", package = "freesurferformats")
lh_annot <- read.fs.annot(lh_annot_file)
axis <- cifti.axis.parcels.from.annot(lh_annot, structure = "lh")
length(axis$parcels)
#> [1] 35
axis$parcels[[1L]]$name
#> [1] "unknown"