write.fs.annot: Write annotation to binary file.

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

Write annotation to binary file.

Description

Write an annotation to a FreeSurfer binary format annotation file in the new format (v2). An annotation (or brain parcellation) assigns each vertex to a label (or region). One of the regions is often called 'unknown' or similar and all vertices which are not relevant for the parcellation are assigned this label.

Usage

write.fs.annot(
  filepath,
  num_vertices = NULL,
  colortable = NULL,
  labels_as_colorcodes = NULL,
  labels_as_indices_into_colortable = NULL,
  fs.annot = NULL
)

Arguments

filepath	string, path to the output file
num_vertices	integer, the number of vertices of the surface. Must be given unless parameter fs.annot is not NULL.
colortable	dataframe that contains one region per row. Required columns are: 'struct_name': character string, the region name. 'r': integer in range 0-255, the RGB color value for the red channel. 'g': same for the green channel. 'b': same for the blue channel. 'a': the alpha (transparency) channel value. Optional columns are: 'code': the color code. Will be computed if not set. Note that you can pass the dataframe returned by read.fs.annot as 'colortable_df'. Only required if labels_as_indices_into_colortable is used.
labels_as_colorcodes	vector of n integers. The first way to specify the labels. Each integer is a colorcode, that has been computed from the RGBA color values of the regions in the colortable as r + g*2^8 + b*2^16 + a*2^24. If you do not already have these color codes, it is way easier to set this to NULL and define the labels as indices into the colortable, see parameter labels_as_indices_into_colortable.
labels_as_indices_into_colortable	vector of n integers, the second way to specify the labels. Each integer is an index into the rows of the colortable. Indices start with 1. This parameter and labels_as_colorcodes are mutually exclusive, but required.
fs.annot	instance of class fs.annot. If passed, this takes precedence over all other parameters and they should all be NULL (with the exception of filepath).

See Also

Other atlas functions: atlas.from.lut.and.csv(), colortable.from.annot(), read.fs.annot(), read.fs.colortable(), write.atlas.to.lut.and.csv(), write.fs.annot.gii(), write.fs.colortable()

Examples

## Not run: 
# Load annotation
annot_file <- system.file("extdata", "lh.aparc.annot.gz",
  package = "freesurferformats",
  mustWork = TRUE
)
annot <- read.fs.annot(annot_file)
# New method: write the annotation instance:
write.fs.annot(tempfile(fileext = ".annot"), fs.annot = annot)
# Old method: write it from its parts:
write.fs.annot(tempfile(fileext = ".annot"), length(annot$vertices),
  annot$colortable_df,
  labels_as_colorcodes = annot$label_codes
)

## End(Not run)

freesurferformats documentation built on Sept. 8, 2026, 5:08 p.m.