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

In freesurferformats: Read and Write 'FreeSurfer' Neuroimaging File Formats

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

Description

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)
axis$parcels[[1L]]$name

freesurferformats documentation built on Sept. 25, 2026, 1:07 a.m.