Compute the centroid of every region of an atlas on a surface.

Computes, for every region of an atlas (annotation), the mean position of the surface vertices that belong to the region. These centroids are the node positions of a connectome visualization, see vis.connectome. This is the equivalent of the _extract_centroids() function of the Python package yabplot.

Usage

subject.region.centroids(
  subjects_dir,
  subject_id,
  atlas,
  surface = "midthickness",
  hemi = "both",
  exclude_regions = c("unknown", "medialwall", "")
)

Arguments

subjects_dir

character string. The FreeSurfer SUBJECTS_DIR, i.e., a directory containing the data for all subjects, each in a subdir named after the subject identifier. Can be NULL for a template subject (like fs_LR_32 or fsaverage), in which case the standard locations (package cache, FreeSurfer installation) are searched.

subject_id

character string, the subject identifier. For a template space, this is the name of the template subject, e.g., 'fs_LR_32' or 'fsaverage'.

atlas

character string, the atlas name, e.g., 'schaefer400', 'brainnetome' or 'aal3'. Used to construct the name of the annotation file.

surface

character string, the name of the surface on which the centroids are computed. Defaults to 'midthickness' (the surface in the middle between white and pial matter), which is the surface usually used for connectome figures.

hemi

character string, one of 'lh', 'rh', or 'both'. Defaults to 'both'.

exclude_regions

vector of character strings, the names of atlas regions to exclude. Defaults to the medial wall and the unknown region, which are not real brain regions.

Value

data.frame with one row per region, the columns 'x', 'y', 'z' (the centroid coordinates), 'region' (the region name) and 'hemi' (the hemisphere). The row names are the region names, which are unique across hemispheres for the atlases that are distributed by fsbrain (see the example).

See also

Other connectome functions: vis.connectome()

Examples

if (FALSE) { # \dontrun{
  # For the fs_LR_32 template (HCP-style), download the data first:
  fsbrain::download_fs_LR_32_meshes();
  fsbrain::download_fs_LR_32_atlases();
  centroids = subject.region.centroids(subjects_dir = NULL, subject_id = "fs_LR_32",
    atlas = "schaefer400", surface = "midthickness");
  head(centroids);
} # }