fsbrain (version 0.1.0)

vis.region.values.on.subject: Visualize arbitrary data, one value per atlas region, on the surface of any subject (including template subjects).

Description

This function can be used for rendering a single value (color) for all vertices of an atlas region. The typical usecase is the visualization of results of atlas-based analyses, e.g., p-value, means or other aggregated values over all vertices of a region.

Usage

vis.region.values.on.subject(
  subjects_dir,
  subject_id,
  atlas,
  lh_region_value_list,
  rh_region_value_list,
  surface = "white",
  colormap = NULL,
  views = c("t4"),
  rgloptions = list(),
  rglactions = list(),
  value_for_unlisted_regions = NA,
  draw_colorbar = FALSE,
  makecmap_options = list(colFn = grDevices::heat.colors),
  bg = NULL
)

Arguments

subjects_dir

string. The FreeSurfer SUBJECTS_DIR, i.e., a directory containing the data for all your subjects, each in a subdir named after the subject identifier.

subject_id

string. The subject identifier.

atlas

string. The brain atlas to use. E.g., 'aparc' or 'aparc.a2009s'.

lh_region_value_list

named list. A list for the left hemisphere in which the names are atlas regions, and the values are the value to write to all vertices of that region.

rh_region_value_list

named list. A list for the right hemisphere in which the names are atlas regions, and the values are the value to write to all vertices of that region.

surface

string. The display surface. E.g., "white", "pial", or "inflated". Defaults to "white".

colormap

a colormap function. **DEPRECATED**: use parameter 'makecmap_options' instead.

views

list of strings. Valid entries include: 'si': single interactive view. 't4': tiled view showing the brain from 4 angles. 't9': tiled view showing the brain from 9 angles.

rgloptions

option list passed to par3d. Example: rgloptions = list("windowRect"=c(50,50,1000,1000)).

rglactions

named list. A list in which the names are from a set of pre-defined actions. The values can be used to specify parameters for the action.

value_for_unlisted_regions

numerical scalar or `NaN`, the value to assign to regions which do not occur in the region_value_lists. Defaults to `NaN`.

draw_colorbar

logical, whether to draw a colorbar. WARNING: The colorbar is drawn to a subplot, and this only works if there is enough space for it. You will have to increase the plot size using the 'rlgoptions' parameter for the colorbar to show up. Defaults to FALSE. See coloredmesh.plot.colorbar.separate for an alternative.

makecmap_options

named list of parameters to pass to makecmap. Must not include the unnamed first parameter, which is derived from 'measure'. Should include at least a colormap function as name 'colFn'.

bg

a background definition. Can be a surface color layer or a character string, see collayer.bg for valid strings.

Value

list of coloredmeshes. The coloredmeshes used for the visualization.

See Also

Other visualization functions: vis.color.on.subject(), vis.data.on.fsaverage(), vis.data.on.subject(), vis.labeldata.on.subject(), vis.mask.on.subject(), vis.subject.annot(), vis.subject.label(), vis.subject.morph.native(), vis.subject.morph.standard(), vis.symmetric.data.on.subject(), vislayout.from.coloredmeshes()

Other region-based visualization functions: vis.subject.annot()

Examples

# NOT RUN {
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   atlas = 'aparc';   # Desikan atlas
   # For the left hemisphere, we just assign a subset of the
   # atlas regions. The others will get the default value.
   lh_region_value_list = list("bankssts"=0.9, "precuneus"=0.7, "postcentral"=0.8, "lingual"=0.6);
   # For the right hemisphere, we retrieve the full list of regions for
   # the atlas, and assign random values to all of them.
   atlas_region_names = get.atlas.region.names(atlas, template_subjects_dir = subjects_dir,
    template_subject='subject1');
   rh_region_value_list = rnorm(length(atlas_region_names), 3.0, 1.0);
   names(rh_region_value_list) = atlas_region_names;
   vis.region.values.on.subject(subjects_dir, 'subject1', atlas,
    lh_region_value_list, rh_region_value_list);
# }
# NOT RUN {
# }