freesurferformats (version 0.1.18)

write.fs.annot: 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: colortable.from.annot(), read.fs.annot(), read.fs.colortable(), write.fs.annot.gii(), write.fs.colortable()

Examples

if (FALSE) {
   # 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);
}