read.fs.annot: Read file in FreeSurfer annotation format
In freesurferformats: Read and Write 'FreeSurfer' Neuroimaging File Formats

Description Usage Arguments Value See Also Examples

Read a data annotation file in FreeSurfer format. Such a file assigns a label and a color to each vertex of a brain surface. The assignment of labels to vertices is based on at atlas or brain parcellation file. Typically the atlas is available for some standard template subject, and the labels are assigned to another subject by registering it to the template. For a subject (MRI image pre-processed with FreeSurfer) named 'bert', an example file would be 'bert/label/lh.aparc.annot', which contains the annotation based on the Desikan-Killiany Atlas for the left hemisphere of bert.

read.fs.annot(
  filepath,
  empty_label_name = "empty",
  metadata = list(),
  default_label_name = ""
)

`filepath`	string. Full path to the input annotation file. Note: gzipped files are supported and gz format is assumed if the filepath ends with ".gz".
`empty_label_name`	character string, a base name to use to rename regions with empty name in the label table. This should not occur, and you can ignore this parameter setting. A warning will be thrown if this ever triggers. Not to be confused with parameter `default_label_name`, see below.
`metadata`	named list of arbitrary metadata to store in the instance.
`default_label_name`	character string, the label name to use for vertices which have a label code that does not occur in the label table. This is typically the case for the 'unknown' region, which often has code `0`. You can set this to avoid empty region label names. The typical setting would be 'unknown', however by default we leave the names as-is, so that annots which are read and then written back to files with this library do not differ.

named list, entries are: "vertices" vector of n vertex indices, starting with 0. "label_codes": vector of n integers, each entry is a color code, i.e., a value from the 5th column in the table structure included in the "colortable" entry (see below). "label_names": the n brain structure names for the vertices, already retrieved from the colortable using the code. "hex_colors_rgb": Vector of hex color for each vertex. The "colortable" is another named list with 3 entries: "num_entries": int, number of brain structures. "struct_names": vector of strings, the brain structure names. "table": numeric matrix with num_entries rows and 5 colums. The 5 columns are: 1 = color red channel, 2=color blue channel, 3=color green channel, 4=color alpha channel, 5=unique color code. "colortable_df": The same information as a dataframe. Contains the extra columns "hex_color_string_rgb" and "hex_color_string_rgba" that hold the color as an RGB(A) hex string, like "#rrggbbaa".

Other atlas functions: colortable.from.annot(), read.fs.colortable(), write.fs.annot.gii(), write.fs.annot(), write.fs.colortable()

    annot_file = system.file("extdata", "lh.aparc.annot.gz",
                               package = "freesurferformats",
                               mustWork = TRUE);
    annot = read.fs.annot(annot_file);
    print(annot);