Type:	Package
Title:	Managing and Visualizing Brain Surface Data
Version:	0.5.5
Maintainer:	Tim Schäfer <ts+code@rcmd.org>
Description:	Provides high-level access to neuroimaging data from standard software packages like 'FreeSurfer' http://freesurfer.net/ on the level of subjects and groups. Load morphometry data, surfaces and brain parcellations based on atlases. Mask data using labels, load data for specific atlas regions only, and visualize data and statistical results directly in 'R'.
License:	MIT + file LICENSE
Encoding:	UTF-8
URL:	https://github.com/dfsp-spirit/fsbrain
BugReports:	https://github.com/dfsp-spirit/fsbrain/issues
Imports:	reshape, freesurferformats (≥ 0.1.17), pkgfilecache (≥ 0.1.1), rgl, squash, fields, viridis, data.table, magick, methods
Suggests:	knitr, rmarkdown, testthat (≥ 2.1.0), sphereplot (≥ 1.5), misc3d, RColorBrewer, Rvcg (≥ 0.20.2), igraph, pracma
VignetteBuilder:	knitr
RoxygenNote:	7.2.3
NeedsCompilation:	no
Packaged:	2024-02-03 10:07:23 UTC; spirit
Author:	Tim Schäfer [aut, cre]
Repository:	CRAN
Date/Publication:	2024-02-03 12:30:02 UTC

Perform alpha blending for pairs of RGBA colors.

Description

Implements the *over* alpha blending operation.

Usage

alphablend(front_color, back_color, silent = TRUE)

Arguments

Value

rgba color strings, the alpha-blended colors

References

see the *Alpha blending* section on https://en.wikipedia.org/wiki/Alpha_compositing

See Also

Other color functions: desaturate()

Compute outline vertex colors from annotation.

Description

For each region in an atlas, compute the outer border and color the respective vertices in the region-specific color from the annot's colortable.

Usage

annot.outline(
  annotdata,
  surface_mesh,
  background = "white",
  silent = TRUE,
  expand_inwards = 0L,
  outline_color = NULL,
  limit_to_regions = NULL
)

Arguments

Value

vector of colors, one color for each mesh vertex

Note

Sorry for the computational time, the mesh datastructure is not ideal for neighborhood search.

Compute the border vertices for each region in an annot.

Description

Compute the border vertices for each region in an annot.

Usage

annot.outline.border.vertices(
  annotdata,
  surface_mesh,
  silent = TRUE,
  expand_inwards = 0L,
  limit_to_regions = NULL
)

Arguments

Value

named list, the keys are the region names and the values are vectors of integers encoding vertex indices.

Load a label from file and apply it to morphometry data.

Description

This function will set all values in morphdata which are *not* part of the label loaded from the file to NA (or whatever is specified by 'masked_data_value'). This is typically used to ignore values which are not part of the cortex (or any other label) during your analysis.

Usage

apply.label.to.morphdata(
  morphdata,
  subjects_dir,
  subject_id,
  hemi,
  label,
  masked_data_value = NA
)

Arguments

Value

numerical vector, the masked data.

See Also

Other label functions: apply.labeldata.to.morphdata(), subject.lobes(), subject.mask(), vis.labeldata.on.subject(), vis.subject.label()

Other morphometry data functions: apply.labeldata.to.morphdata(), group.morph.native(), group.morph.standard(), subject.morph.native(), subject.morph.standard()

Apply a label to morphometry data.

Description

This function will set all values in morphdata which are *not* part of the labeldata to NA (or whatever is specified by 'masked_data_value'). This is typically used to ignore values which are not part of the cortex (or any other label) during your analysis.

Usage

apply.labeldata.to.morphdata(morphdata, labeldata, masked_data_value = NA)

Arguments

Value

numerical vector, the masked data.

See Also

Other label functions: apply.label.to.morphdata(), subject.lobes(), subject.mask(), vis.labeldata.on.subject(), vis.subject.label()

Other morphometry data functions: apply.label.to.morphdata(), group.morph.native(), group.morph.standard(), subject.morph.native(), subject.morph.standard()

Apply matmult transformation to input.

Description

Apply affine transformation, like a *vox2ras_tkr* transformation, to input. This is just matrix multiplication for different input objects.

Usage

apply.transform(object, matrix_fun)

Arguments

Value

the input after application of the affine matrix (matrix multiplication)

Combine several brainview images into a new figure.

Description

Create a new image from several image tiles, the exact layout depends on the number of given images.

Usage

arrange.brainview.images(
  brainview_images,
  output_img,
  colorbar_img = NULL,
  silent = TRUE,
  grid_like = TRUE,
  border_geometry = "5x5",
  background_color = "white",
  map_bg_to_transparency = FALSE
)

Arguments

Value

named list with entries: 'brainview_images': vector of character strings, the paths to the input images. 'output_img_path': character string, path to the output image. 'merged_img': the magick image instance.

Combine several brainview images as a grid into a new figure.

Description

Create a new image from several image tiles, the exact layout is a grid with n per row.

Usage

arrange.brainview.images.grid(
  brainview_images,
  output_img,
  colorbar_img = NULL,
  silent = TRUE,
  num_per_row = 10L,
  border_geometry = "5x5",
  background_color = "white",
  captions = NULL
)

Arguments

Value

named list with entries: 'brainview_images': vector of character strings, the paths to the input images. 'output_img_path': character string, path to the output image. 'merged_img': the magick image instance.

Note

The tiles are written row-wise, in the order in which they occur in the parameter 'brainview_images'.

Compute the coordinates of the 8 corners of a 3D box.

Description

Given the extreme values (min and max) along the 3 axes, compute the coordinates of the 8 corners of a 3D box.

Usage

boxcoords.from.bbox(axes_min, axes_max)

Arguments

Value

numerical matrix with 3 columns and 8 rows, the edge coordinates

Create fsbrain instance from 2 coloredmeshes.

Description

Create fsbrain instance from 2 coloredmeshes.

Usage

brain(lh_cm, rh_cm)

Arguments

Value

fsbrain instance

Visualize a list of colored meshes from a single defined angle.

Description

Visualize a list of colored meshes from a single defined angle.

Usage

brainview.sd(
  coloredmeshes,
  view_angle,
  background = "white",
  skip_all_na = TRUE,
  style = "default",
  rgloptions = rglo(),
  rglactions = list(),
  draw_colorbar = FALSE
)

Arguments

Visualize a list of colored meshes from a single viewpoint, interactively.

Description

Visualize a list of colored meshes from a single viewpoint, interactively.

Usage

brainview.si(
  coloredmeshes,
  background = "white",
  skip_all_na = TRUE,
  style = "default",
  draw_labels = FALSE,
  rgloptions = rglo(),
  rglactions = list(),
  draw_colorbar = FALSE
)

Arguments

Visualize a list of colored meshes, rotating the camera around them.

Description

Visualize a list of colored meshes, rotating the camera around them.

Usage

brainview.sr(
  coloredmeshes,
  background = "white",
  skip_all_na = TRUE,
  style = "default",
  draw_labels = FALSE,
  x = 0,
  y = 1,
  z = 0,
  rpm = 6,
  duration = 10,
  rgloptions = rglo(),
  rglactions = list(),
  draw_colorbar = FALSE
)

Arguments

Visualize a list of colored meshes from four angles.

Description

Visualize a list of colored meshes from four angles.

Usage

brainview.t4(
  coloredmeshes,
  background = "white",
  skip_all_na = TRUE,
  style = "default",
  draw_labels = FALSE,
  rgloptions = rglo(),
  rglactions = list(),
  draw_colorbar = FALSE
)

Arguments

Visualize a list of colored meshes from nine angles.

Description

Visualize a list of colored meshes from nine angles.

Usage

brainview.t9(
  coloredmeshes,
  background = "white",
  skip_all_na = TRUE,
  style = "default",
  draw_labels = FALSE,
  rgloptions = rglo(),
  rglactions = list(),
  draw_colorbar = FALSE
)

Arguments

Show one or more views of the given meshes in rgl windows.

Description

Show one or more views of the given meshes in rgl windows.

Usage

brainviews(
  views,
  coloredmeshes,
  rgloptions = rglo(),
  rglactions = list(),
  style = "default",
  draw_colorbar = FALSE,
  background = "white"
)

Arguments

Value

list of coloredmeshes. The coloredmeshes used for the visualization.

See Also

get.view.angle.names

Determine whether colorbar can be plotted with given metadata.

Description

Determine whether colorbar can be plotted with given metadata.

Usage

can.plot.colorbar(combined_data_range, makecmap_options)

Arguments

Value

logical, whether the metadata suffices to plot a colorbar

Determine whether colorbar can be plotted with given coloredmeshes.

Description

Determine whether colorbar can be plotted with given coloredmeshes.

Usage

can.plot.colorbar.from.coloredmeshes(coloredmeshes)

Arguments

Value

logical, whether the metadata suffices to plot a colorbar

Report subjects missing files

Description

Report subjects missing files

Usage

check.subjects.files(
  subjects_dir,
  subjects_list,
  sfiles = c("surf/lh.thickness", "surf/rh.thickness", "surf/lh.white", "surf/rh.white",
    "label/lh.aparc.annot", "label/rh.aparc.annot")
)

Arguments

Value

vector of character strings, the subjects missing any of the files.

Check whether the subjects_list looks good, warn if not.

Description

Check whether the subjects_list looks good, warn if not.

Usage

check.subjectslist(
  subjects_list,
  subjects_dir = NULL,
  report_name = "subjects_list"
)

Arguments

Note

This function will stop if subjects dirs are missing.

Clip data at quantiles to remove outliers.

Description

Set all data values outside the given quantile range to the border values. This is useful to properly visualize morphometry data that includes outliers. These outliers negatively affect the colormap, as all the non-outlier values become hard to distinguish. This function can be used to filter the data before plotting it.

Usage

clip.data(data, lower = 0.05, upper = 0.95)

Arguments

Value

numeric vector. The output data.

See Also

The clip_fun function is more convenient when used in rglactions, as it allows specification of custom quantiles.

Examples

   full_data = rnorm(50, 3, 1);
   clipped = clip.data(full_data);

Get data clipping function.

Description

Get data clipping function to use in rglactions as 'trans_fun' to transform data. This is typically used to limit the colorbar in a plot to a certain range. This uses percentiles to clip. Clipping means that values more extreme than the gíven quantiles will be set to the quantile values.

Usage

clip_fun(lower = 0.05, upper = 0.95)

Arguments

Value

a function that takes as argument the data, and clips it to the requested range. I.e., values outside the range will be set to the closest border value. Designed to be used as rglactions$trans_fun in vis functions, to limit the colorbar and data range.

See Also

rglactions

Examples

   rglactions = list("trans_fun"=clip_fun(0.10, 0.90));
   rglactions = list("trans_fun"=clip_fun());
   f = clip_fun();
   f(rnorm(100));

Get cyan blue red yellow colormap function.

Description

Get cyan blue red yellow colormap function.

Usage

cm.cbry()

Note

Returns a diverging palette with negative values in blue/cyan and positive ones in red/yellow, suitable for visualizing data that is centered around zero. Often used for clusters in neuroscience.

Return the standard fsbrain diverging colormap.

Description

Return the standard fsbrain diverging colormap.

Usage

cm.div(report = FALSE)

Arguments

Note

Returns some diverging palette, suitable for visualizing data that is centered around zero.

Return the standard fsbrain heat colormap.

Description

Return the standard fsbrain heat colormap.

Usage

cm.heat(report = FALSE)

Arguments

Note

The heat palette is a sequential, single-hue palette.

Return the standard fsbrain qualitative colormap.

Description

Return the standard fsbrain qualitative colormap.

Usage

cm.qual(report = FALSE)

Arguments

Note

Returns some qualitative palette, suitable for visualizing categorical data.

Return the standard fsbrain sequential colormap.

Description

Return the standard fsbrain sequential colormap.

Usage

cm.seq(report = FALSE)

Arguments

Note

This returns a sequential, multi-hue palette.

Compute binarized mean curvature surface color layer.

Description

Compute a binarized mean curvature surface color layer, this is intended as a background color layer. You can merge it with your data layer using collayers.merge.

Usage

collayer.bg(subjects_dir, subject_id, bg, hemi = "both")

Arguments

Value

a color layer, i.e., vector of color strings in a hemilist

See Also

You can plot the return value using vis.color.on.subject.

Other surface color layer: collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg.sulc(), collayer.from.annotdata(), collayer.from.annot(), collayer.from.mask.data(), collayer.from.morphlike.data(), collayers.merge()

Compute atlas or annotation surface color layer.

Description

Compute atlas or annotation surface color layer.

Usage

collayer.bg.atlas(
  subjects_dir,
  subject_id,
  hemi = "both",
  atlas = "aparc",
  grayscale = FALSE,
  outline = FALSE,
  outline_surface = "white"
)

Arguments

Value

a color layer, i.e., vector of color strings in a hemilist

Note

Using 'outline' mode is quite slow, and increasing the border thickness makes it even slower.

See Also

You can plot the return value using vis.color.on.subject.

Other surface color layer: collayer.bg.meancurv(), collayer.bg.sulc(), collayer.bg(), collayer.from.annotdata(), collayer.from.annot(), collayer.from.mask.data(), collayer.from.morphlike.data(), collayers.merge()

Compute binarized mean curvature surface color layer.

Description

Compute a binarized mean curvature surface color layer, this is intended as a background color layer. You can merge it with your data layer using collayers.merge.

Usage

collayer.bg.meancurv(
  subjects_dir,
  subject_id,
  hemi = "both",
  cortex_only = FALSE,
  bin_colors = c("#898989", "#5e5e5e"),
  bin_thresholds = c(0)
)

Arguments

Value

a color layer, i.e., vector of color strings in a hemilist

See Also

You can plot the return value using vis.color.on.subject.

Other surface color layer: collayer.bg.atlas(), collayer.bg.sulc(), collayer.bg(), collayer.from.annotdata(), collayer.from.annot(), collayer.from.mask.data(), collayer.from.morphlike.data(), collayers.merge()

Compute binarized sulcal depth surface color layer.

Description

Compute a binarized sulcal depth surface color layer, this is intended as a background color layer. You can merge it with your data layer using collayers.merge.

Usage

collayer.bg.sulc(
  subjects_dir,
  subject_id,
  hemi = "both",
  cortex_only = FALSE,
  bin_colors = c("#898989", "#5e5e5e"),
  bin_thresholds = c(0)
)

Arguments

Value

a color layer, i.e., vector of color strings in a hemilist

See Also

You can plot the return value using vis.color.on.subject.

Other surface color layer: collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg(), collayer.from.annotdata(), collayer.from.annot(), collayer.from.mask.data(), collayer.from.morphlike.data(), collayers.merge()

Compute surface color layer from annotation or atlas data.

Description

Compute surface color layer from annotation or atlas data.

Usage

collayer.from.annot(subjects_dir, subject_id, hemi, atlas)

Arguments

Value

named hemi list, each entry is a vector of color strings, one color per surface vertex. The coloring represents the atlas data.

See Also

You can plot the return value using vis.color.on.subject.

Other surface color layer: collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg.sulc(), collayer.bg(), collayer.from.annotdata(), collayer.from.mask.data(), collayer.from.morphlike.data(), collayers.merge()

Compute surface color layer from annotation or atlas data.

Description

Compute surface color layer from annotation or atlas data.

Usage

collayer.from.annotdata(lh_annotdata = NULL, rh_annotdata = NULL)

Arguments

Value

named hemi list, each entry is a vector of color strings, one color per surface vertex. The coloring represents the atlas data.

See Also

You can plot the return value using vis.color.on.subject.

Other surface color layer: collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg.sulc(), collayer.bg(), collayer.from.annot(), collayer.from.mask.data(), collayer.from.morphlike.data(), collayers.merge()

Compute surface color layer from morph-like data.

Description

Compute surface color layer from morph-like data.

Usage

collayer.from.mask.data(
  lh_data = NULL,
  rh_data = NULL,
  makecmap_options = list(colFn = label.colFn)
)

Arguments

Value

named hemi list, each entry is a vector of color strings, one color per surface vertex. The coloring represents the label data.

See Also

You can plot the return value using vis.color.on.subject.

Other surface color layer: collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg.sulc(), collayer.bg(), collayer.from.annotdata(), collayer.from.annot(), collayer.from.morphlike.data(), collayers.merge()

Compute surface color layer from morph-like data.

Description

Compute surface color layer from morph-like data.

Usage

collayer.from.morphlike.data(
  lh_morph_data = NULL,
  rh_morph_data = NULL,
  makecmap_options = list(colFn = cm.seq()),
  return_metadata = FALSE
)

Arguments

Value

named hemi list, each entry is a vector of color strings, one color per surface vertex. The coloring represents the morph data.

See Also

You can plot the return value using vis.color.on.subject.

Other surface color layer: collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg.sulc(), collayer.bg(), collayer.from.annotdata(), collayer.from.annot(), collayer.from.mask.data(), collayers.merge()

Merge two or more color layers based on their transparency values.

Description

Merge several color layers into one based on their transparency and alpha blending. In the final result, the lower layers are visible through the transparent or 'NA' parts (if any) of the upper layers.

Usage

collayers.merge(collayers, opaque_background = "#FFFFFF")

Arguments

Value

a color layer, i.e., vector of color strings in a hemilist

See Also

Other surface color layer: collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg.sulc(), collayer.bg(), collayer.from.annotdata(), collayer.from.annot(), collayer.from.mask.data(), collayer.from.morphlike.data()

Create a coloredmesh from an annotation of an atlas.

Description

Create a coloredmesh from an annotation of an atlas.

Usage

coloredmesh.from.annot(
  subjects_dir,
  subject_id,
  atlas,
  hemi,
  surface = "white",
  outline = FALSE
)

Arguments

Value

coloredmesh. A named list with entries: "mesh" the tmesh3d mesh object. "col": the mesh colors. "render", logical, whether to render the mesh. "hemi": the hemisphere, one of 'lh' or 'rh'.

See Also

Other coloredmesh functions: coloredmesh.from.label(), coloredmesh.from.mask(), coloredmesh.from.morph.native(), coloredmesh.from.morph.standard(), coloredmesh.from.morphdata(), coloredmeshes.from.color()

Create a coloredmesh from a mesh and pre-defined colors.

Description

Create a coloredmesh from a mesh and pre-defined colors.

Usage

coloredmesh.from.color(
  subjects_dir,
  subject_id,
  color_data,
  hemi,
  surface = "white",
  metadata = list()
)

Arguments

Value

coloredmesh. A named list with entries: "mesh" the tmesh3d mesh object. "col": the mesh colors. "render", logical, whether to render the mesh. "hemi": the hemisphere, one of 'lh' or 'rh'.

Note

Do not call this directly, use coloredmeshes.from.color instead.

Create a coloredmesh from a label.

Description

Create a coloredmesh from a label.

Usage

coloredmesh.from.label(
  subjects_dir,
  subject_id,
  label,
  hemi,
  surface = "white",
  makecmap_options = list(colFn = squash::rainbow2),
  binary = TRUE
)

Arguments

Value

coloredmesh. A named list with entries: "mesh" the tmesh3d mesh object. "col": the mesh colors. "render", logical, whether to render the mesh. "hemi": the hemisphere, one of 'lh' or 'rh'.

See Also

Other coloredmesh functions: coloredmesh.from.annot(), coloredmesh.from.mask(), coloredmesh.from.morph.native(), coloredmesh.from.morph.standard(), coloredmesh.from.morphdata(), coloredmeshes.from.color()

Create a coloredmesh from a mask.

Description

Create a coloredmesh from a mask.

Usage

coloredmesh.from.mask(
  subjects_dir,
  subject_id,
  mask,
  hemi,
  surface = "white",
  surface_data = NULL,
  makecmap_options = list(colFn = squash::rainbow2)
)

Arguments

Value

coloredmesh. A named list with entries: "mesh" the tmesh3d mesh object. "col": the mesh colors. "render", logical, whether to render the mesh. "hemi": the hemisphere, one of 'lh' or 'rh'.

See Also

Other mask functions: mask.from.labeldata.for.hemi(), vis.mask.on.subject()

Other coloredmesh functions: coloredmesh.from.annot(), coloredmesh.from.label(), coloredmesh.from.morph.native(), coloredmesh.from.morph.standard(), coloredmesh.from.morphdata(), coloredmeshes.from.color()

Create a coloredmesh from native space morphometry data.

Description

Create a coloredmesh from native space morphometry data.

Usage

coloredmesh.from.morph.native(
  subjects_dir,
  subject_id,
  measure,
  hemi,
  surface = "white",
  clip = NULL,
  cortex_only = FALSE,
  makecmap_options = mkco.seq()
)

Arguments

Value

coloredmesh. A named list with entries: "mesh" the tmesh3d mesh object. "col": the mesh colors. "render", logical, whether to render the mesh. "hemi": the hemisphere, one of 'lh' or 'rh'.

See Also

Other coloredmesh functions: coloredmesh.from.annot(), coloredmesh.from.label(), coloredmesh.from.mask(), coloredmesh.from.morph.standard(), coloredmesh.from.morphdata(), coloredmeshes.from.color()

Create a coloredmesh from standard space morphometry data.

Description

Create a coloredmesh from standard space morphometry data.

Usage

coloredmesh.from.morph.standard(
  subjects_dir,
  subject_id,
  measure,
  hemi,
  fwhm,
  surface = "white",
  template_subject = "fsaverage",
  template_subjects_dir = NULL,
  clip = NULL,
  cortex_only = FALSE,
  makecmap_options = mkco.seq()
)

Arguments

Value

coloredmesh. A named list with entries: "mesh" the tmesh3d mesh object. "col": the mesh colors. "render", logical, whether to render the mesh. "hemi": the hemisphere, one of 'lh' or 'rh'.

See Also

Other coloredmesh functions: coloredmesh.from.annot(), coloredmesh.from.label(), coloredmesh.from.mask(), coloredmesh.from.morph.native(), coloredmesh.from.morphdata(), coloredmeshes.from.color()

Create a coloredmesh from arbitrary data.

Description

Create a coloredmesh from arbitrary data.

Usage

coloredmesh.from.morphdata(
  subjects_dir,
  vis_subject_id,
  morph_data,
  hemi,
  surface = "white",
  makecmap_options = mkco.seq()
)

Arguments

Value

coloredmesh. A named list with entries: "mesh" the tmesh3d mesh object. "col": the mesh colors. "render", logical, whether to render the mesh. "hemi": the hemisphere, one of 'lh' or 'rh'.

See Also

Other coloredmesh functions: coloredmesh.from.annot(), coloredmesh.from.label(), coloredmesh.from.mask(), coloredmesh.from.morph.native(), coloredmesh.from.morph.standard(), coloredmeshes.from.color()

Generate coloredmesh from loaded data.

Description

Generate coloredmesh from loaded data.

Usage

coloredmesh.from.preloaded.data(
  fs_surface,
  morph_data = NULL,
  col = NULL,
  hemi = "lh",
  makecmap_options = mkco.seq()
)

Arguments

Value

as fs.coloredmesh instance

Draw colorbar for coloredmeshes in separate 2D plot.

Description

Draw a colorbar for the coloredmeshes to a separate 2D plot. Due to the suboptimal handling of colorbar drawing in the three-dimensional multi-panel views, it is often desirable to plot the colorbar in a separate window, export it from there and then manually add it to the final plot version in some image manipulation software like Inkscape. If you need more control over the colormap than offered by this function (e.g., setting the color value for NA values or making a symmetric colormap to ensure that the zero point for divergent colormaps is a neutral color), you should write custom code, and the return value from this function will come in handy to do that.

Usage

coloredmesh.plot.colorbar.separate(
  coloredmeshes,
  show = FALSE,
  image.plot_extra_options = list(horizontal = FALSE, legend.cex = 1.8, legend.width = 2,
    legend.mar = 12, axis.args = list(cex.axis = 5)),
  png_options = list(filename = "fsbrain_cbar.png", width = 1400, height = 1400, bg =
    "#FFFFFF00"),
  silent = FALSE,
  trim_png = TRUE,
  log_breaks = FALSE
)

Arguments

Value

named list, entries: 'output_img_path': character string, the path to the output file, or NULL.

Note

If you increase the output resolution of the colorbar (using 'png_options'), you will have to increase the font sizes as well (using 'image.plot_extra_options'), otherwise the axis and legend labels will be hard to read.

See Also

Other colorbar functions: combine.colorbar.with.brainview.animation(), combine.colorbar.with.brainview.image()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   coloredmeshes = vis.subject.morph.native(subjects_dir, 'subject1',
    'thickness', 'lh', views=c('t4'));
   coloredmesh.plot.colorbar.separate(coloredmeshes);

   # Or plot a colorbar with a label:
   coloredmesh.plot.colorbar.separate(coloredmeshes,
    image.plot_extra_options = list("legend.lab"="Thickness [mm]",
    horizontal=TRUE, legend.cex=1.5, legend.line=-3));

## End(Not run)

Retrieve combined data range from hemilist of coloredmeshes.

Description

Retrieve combined data range from hemilist of coloredmeshes.

Usage

coloredmeshes.combined.data.range(coloredmeshes)

Arguments

Value

numeric vector of length 2, the finite data range

Create coloredmeshes for both hemis using pre-defined colors.

Description

Create coloredmeshes for both hemis using pre-defined colors.

Usage

coloredmeshes.from.color(
  subjects_dir,
  subject_id,
  color_data,
  hemi,
  surface = "white",
  metadata = list()
)

Arguments

Value

named list of coloredmeshes. Each entry is a named list with entries: "mesh" the tmesh3d mesh object. "col": the mesh colors. "render", logical, whether to render the mesh. "hemi": the hemisphere, one of 'lh' or 'rh'.

See Also

Other coloredmesh functions: coloredmesh.from.annot(), coloredmesh.from.label(), coloredmesh.from.mask(), coloredmesh.from.morph.native(), coloredmesh.from.morph.standard(), coloredmesh.from.morphdata()

Retrieve metadata from hemilist of coloredmeshes.

Description

Retrieve metadata from hemilist of coloredmeshes.

Usage

coloredmeshes.get.md(coloredmeshes, mdname)

Arguments

Value

the metadata value at the given key/mdname

Return diverging color list

Description

Return diverging color list

Usage

colorlist.brain.clusters(num_colors)

Arguments

Value

vector of colors

Check for the given color strings whether they represent gray scale colors.

Description

Check for the given color strings whether they represent gray scale colors.

Usage

colors.are.grayscale(col_strings, accept_col_names = TRUE)

Arguments

Value

logical vector

Examples

colors.are.grayscale(c("#FFFFFF", "#FF00FF"));
all((colors.are.grayscale(c("#FFFFFF00", "#ABABABAB"))));

Check for the given color strings whether they have transparency, i.e., an alpha channel value != fully opaque.

Description

Check for the given color strings whether they have transparency, i.e., an alpha channel value != fully opaque.

Usage

colors.have.transparency(col_strings, accept_col_names = TRUE)

Arguments

Value

logical vector

Examples

colors.have.transparency(c("#FFFFFF", "#FF00FF", "#FF00FF00", "red", "#FF00FFDD"));
all((colors.have.transparency(c("#FFFFFF00", "#ABABABAB"))));

Combine a colorbar and a brain animation in gif format into a new animation.

Description

Combine a colorbar and a brain animation in gif format into a new animation.

Usage

combine.colorbar.with.brainview.animation(
  brain_animation,
  colorbar_img,
  output_animation,
  offset = "+0+0",
  extend_brainview_img_height_by = 0L,
  silent = FALSE,
  allow_colorbar_shrink = TRUE,
  background_color = "white"
)

Arguments

See Also

Other colorbar functions: coloredmesh.plot.colorbar.separate(), combine.colorbar.with.brainview.image()

Combine a colorbar and a brainview image into a new figure.

Description

Combine a colorbar and a brainview image into a new figure.

Usage

combine.colorbar.with.brainview.image(
  brainview_img = "fsbrain_arranged.png",
  colorbar_img = "fsbrain_cbar.png",
  output_img = "fsbrain_merged.png",
  offset = "+0+0",
  extend_brainview_img_height_by = NULL,
  silent = FALSE,
  allow_colorbar_shrink = TRUE,
  horizontal = FALSE,
  background_color = "#FFFFFF",
  transparency_color = NULL,
  delete_colorbar_img = TRUE
)

Arguments

Value

named list with entries 'output_img_path': character string, path to saved image. 'merged_img': magick image instance, the merged image

See Also

Other colorbar functions: coloredmesh.plot.colorbar.separate(), combine.colorbar.with.brainview.animation()

Combine a vertical colorbar and a brainview image into a new figure.

Description

Combine a vertical colorbar and a brainview image into a new figure.

Usage

combine.colorbar.with.brainview.image.vertical(
  brainview_img,
  colorbar_img,
  output_img,
  offset = "+0+0",
  extend_brainview_img_width_by = NULL,
  silent = FALSE,
  allow_colorbar_shrink = TRUE,
  background_color = "#FFFFFF",
  transparency_color = NULL,
  delete_colorbar_img = TRUE
)

Arguments

Get cmap and colorlayer from data and makecmap_options.

Description

Applies a requested 'range' setting if present in makecmap_options. A shared colormap is used for the data of both hemispheres (if present).

Usage

common.makecmap.range(
  makecmap_options,
  lh_data = NULL,
  rh_data = NULL,
  return_metadata = FALSE
)

Arguments

Value

named list, with entries 'map': named list, the squash cmap, and 'collayer': hemilist of color vectors

Get vertex data for a single fs.surface or a hemilist of surfaces.

Description

Get vertex data for a single fs.surface or a hemilist of surfaces.

Usage

constant.pervertexdata(surfaces, value = NA)

Arguments

Value

a vector or hemilist of vectors of values

Return triangles for a 3D cube or cuboid.

Description

Each row of the returned matrix encodes a point (the x, y, and z coordinates), and 3 consecutive rows encode a triangle. Obvisouly, a point will occur several times (as part of several triangles). The result can be passed to triangles3d to render a 3D box. The defaults for the parameters will create a cube with edge length 1 centered at (0, 0, 0).

Usage

cube3D.tris(
  xmin = -0.5,
  xmax = 0.5,
  ymin = -0.5,
  ymax = 0.5,
  zmin = -0.5,
  zmax = 0.5,
  center = NULL,
  edge_length = 1
)

Arguments

Value

numerical matrix with 36 rows and 3 columns, the 3D coordinates. Each row encodes a point (the x, y, and z coordinates), and 3 consecutive rows encode a triangle.

Examples

   # Create a cube with edge length 2, centered at (3,4,5):
   cube_coords = cube3D.tris(center=c(3,4,5), edge_length=2.0);
   # Create the same cube using the min/max method:
   cube_coords = cube3D.tris(xmin=2, xmax=4, ymin=3, ymax=5, zmin=4, zmax=6);
   # Create a cuboid:
   cuboid_coords = cube3D.tris(xmin=2, xmax=4, ymin=3, ymax=9, zmin=4, zmax=5);
   # To render the cuboid:
   #rgl::triangles3d(cuboid_coords, col="red");

Vectorized version of cube3D.tris

Description

Vectorized version of cube3D.tris

Usage

cubes3D.tris(centers, edge_length = 1)

Arguments

Value

matrix of triangle coordinates, see cube3D.tris.

Examples

   # Plot a 3D cloud of 20000 voxels:
   centers = matrix(rnorm(20000*3)*100, ncol=3);
   rgl::triangles3d(cubes3D.tris(centers));

Write deepcopy list for longitudinal subjects.

Description

Write deepcopy list for longitudinal subjects.

Usage

deepcopylist.long(
  measures = c("thickness", "area", "volume"),
  fwhms = c("5", "10", "15"),
  hemis = c("lh", "rh"),
  long_measures = c("avg", "rate", "spc", "pc1"),
  template = "fsaverage",
  has_stacked_file = TRUE,
  output_file = NULL
)

Value

vector of character strings, the file entries. Set ouput_file to also write them to a file.

Convert degree to radians

Description

Convert degree to radians

Usage

deg2rad(deg)

Delete all data in the package cache.

Description

Delete all data in the package cache.

Usage

delete_all_optional_data()

Value

integer. The return value of the unlink() call: 0 for success, 1 for failure. See the unlink() documentation for details.

Show demo visualization to test whether fsbrain is setup correctly.

Description

Show demo visualization to test whether fsbrain is setup correctly.

Usage

demo()

Note

This function will try to download optional data from the internet (unless the data have already been downloaded).

Write FreeSurfer Group Descriptor (FSGD) file from demographics dataframe.

Description

Write FreeSurfer Group Descriptor (FSGD) file from demographics dataframe.

Usage

demographics.to.fsgd.file(
  filepath,
  demographics_df,
  group_column_name = "group",
  subject_id_column_name = "id",
  var_columns = NULL,
  ftitle = "OSGM",
  fsgd_flag_lines = c("DeMeanFlag 1", "ReScaleFlag 1")
)

Arguments

Value

vector of character strings, the lines written to the 'filepath', invisible.

See Also

Other metadata functions: read.md.demographics(), read.md.subjects(), report.on.demographics()

Convert a dataframe containing demographics data to a qdec.table.dat file and related files.

Description

This creates the 'qdec.table.dat' and all required related files (the factor level files) in a directory.

Usage

demographics.to.qdec.table.dat(
  df,
  output_path = ".",
  long = FALSE,
  add_fake_level2 = FALSE,
  long_timecolumn = "years",
  qdec_file_name = "qdec.table.dat"
)

Arguments

Note

IMPORTANT: If you import the dataframe from a text file with functions like read.table, they will by default replace dashes in column names with dots. So if you have a column named fsid-base in there, after loading it will be named fsid.base. See the check.names parameter for read.table to prevent that.

See Also

The function qdec.table.skeleton to generate the data.frame used as the 'df' argument for this function.

Examples

## Not run: 
   dem = readxl::read_xls("~/data/study1/demographics.xsl");
   # or: dem = read.table("~/demographics.csv", check.names=FALSE);
   # You may want to rearrange/rename/delete some columns here.
   demographics.to.qdec.table.dat(dem, "~/data/study1/qdec/");
   #
   # a second one with real data:
   dem = data.frame("ID"=paste("subject", seq(5), sep=""),
      "age"=sample.int(20, 5)+10L, "isi"=rnorm(5, 2.0, 0.1)); #sample data.
   long_table = qdec.table.skeleton(dem$ID, dem$isi);
   demographics.to.qdec.table.dat(long_table, long=TRUE);

## End(Not run)

Perform simple desaturation or grayscale conversion of RGBA colors.

Description

Perform simple desaturation or grayscale conversion of RGBA colors.

Usage

desaturate(color, gamma_correct = FALSE)

Arguments

Value

rgba color strings, the grayscale colors. The information from one of the three rgb channels would be enough. The alpha value is not touched.

Note

Assumes sRGB color space.

References

see https://en.wikipedia.org/wiki/Grayscale#Converting_color_to_grayscale

See Also

Other color functions: alphablend()

Download the FreeSurfer v6 fsaverage subject.

Description

Download some relevant files from the FreeSurfer v6 fsaverage subject. The files are subject to the FreeSurfer software license, see parameter 'accept_freesurfer_license' for details. This data is not required for the package to work. If you are working on a machine that has FreeSurfer installed, you already have this data anyways and do not need to download it. If not, it is very convenient to have it if you are using the fsaverage template subject to analyze your standard space data, as it is required for visualization of such data.

Usage

download_fsaverage(accept_freesurfer_license = FALSE)

Arguments

Value

Named list. The list has entries: "available": vector of strings. The names of the files that are available in the local file cache. You can access them using get_optional_data_file(). "missing": vector of strings. The names of the files that this function was unable to retrieve.

Download the FreeSurfer v6 low-resolution fsaverage3 subject.

Description

Download some relevant files from the FreeSurfer v6 fsaverage3 subject. The files are subject to the FreeSurfer software license, see parameter 'accept_freesurfer_license' for details. This data is not required for the package to work. If you are working on a machine that has FreeSurfer installed, you already have this data anyways and do not need to download it. Also downloads data for subject1 that has been mapped to fsaverage.

Usage

download_fsaverage3(accept_freesurfer_license = FALSE)

Arguments

Value

Named list. The list has entries: "available": vector of strings. The names of the files that are available in the local file cache. You can access them using get_optional_data_file(). "missing": vector of strings. The names of the files that this function was unable to retrieve.

Note

The subject fsaverage3 is a downsampled (low mesh resolution) version of the standard fsaverage. If you never heard about fsaverage3, you do not need it. You will have to manually re-sample your data in FreeSurfer if you want to use it with fsaverage3.

Download optional data for this package if required.

Description

Ensure that the optioanl data is available locally in the package cache. Will try to download the data only if it is not available. This data is not required for the package to work, but it is used in the examples, in the unit tests and also in the example code from the vignette. Downloading it is highly recommended.

Usage

download_optional_data()

Value

Named list. The list has entries: "available": vector of strings. The names of the files that are available in the local file cache. You can access them using get_optional_data_file(). "missing": vector of strings. The names of the files that this function was unable to retrieve.

Download extra data to reproduce the figures from the fsbrain paper.

Description

Download extra data to reproduce the figures from the fsbrain paper.

Usage

download_optional_paper_data()

Value

Named list. The list has entries: "available": vector of strings. The names of the files that are available in the local file cache. You can access them using get_optional_data_file(). "missing": vector of strings. The names of the files that this function was unable to retrieve.

Note

Called for side effect of data download.

Draw colorbar into background of current plot.

Description

Requires a rgl 3d visualisation to be open that already contains a rendered object. Uses bgplot3d to add a colorbar in the background of the plot using image.plot. Experimental.

Usage

draw.colorbar(coloredmeshes, horizontal = FALSE, ...)

Arguments

Note

To adapt or change the colormap, you should use the 'makecmap_options' parameter of the vis.* function used to construct the coloredmeshes (e.g., vis.subject.morph.native).

Internal function to get some demo EEG electrode coordinates. Will be removed from public API. Do not use this.

Description

Internal function to get some demo EEG electrode coordinates. Will be removed from public API. Do not use this.

Usage

eeg_coords(label_subset = NULL)

Arguments

Value

data.frame with one row per electrode, and the following 3 columns: 'label': the electrode name, 'theta': the azimuth in degrees, 'phi': the latitude in degrees.

Note

There are lots of different naming conventions for spherical coordinates, see https://en.wikipedia.org/wiki/Spherical_coordinate_system.

References

See http://wiki.besa.de/index.php?title=Electrodes_and_Surface_Locations

Check whether parameter is an fs.surface instance.

Description

Check whether parameter is an fs.surface instance.

Usage

ensure.fs.surface(surface)

Arguments

Value

an fs.surface instance, unless an error occurs.

Ensure the mesh is a tmesh3d instance. Will convert fs.surfaces to one automatically.

Description

Ensure the mesh is a tmesh3d instance. Will convert fs.surfaces to one automatically.

Usage

ensure.tmesh3d(mesh)

Arguments

Value

tmesh3d instance, the input or converted from the input.

Note

This function will stop if the mesh cannot be converted to tmesh3d.

Export high-quality brainview image with a colorbar.

Description

This function serves as an easy (but slightly inflexible) way to export a high-quality, tight-layout, colorbar figure to disk. If no colorbar is required, one can use vislayout.from.coloredmeshes instead. It is an alias for 'vis.export.from.coloredmeshes' that requires less typing.

Usage

export(
  coloredmeshes,
  colorbar_legend = NULL,
  img_only = TRUE,
  draw_colorbar = "horizontal",
  horizontal = NULL,
  silent = TRUE,
  quality = 1L,
  output_img = "fsbrain_arranged.png",
  image.plot_extra_options = NULL,
  large_legend = TRUE,
  view_angles = get.view.angle.names(angle_set = "t4"),
  style = "default",
  grid_like = TRUE,
  background_color = "white",
  transparency_color = NULL,
  ...
)

Arguments

Value

magick image instance or named list, depending on the value of 'img_only'. If the latter, the list contains the fields 'rev_vl', 'rev_cb', and 'rev_ex', which are the return values of the functions vislayout.from.coloredmeshes, coloredmesh.plot.colorbar.separate, and combine.colorbar.with.brainview.image, respectively.

Note

Note that your screen resolution has to be high enough to generate the final image in the requested resolution, see the 'fsbrain FAQ' vignette for details and solutions if you run into trouble.

Examples

## Not run: 
    rand_data = rnorm(327684, 5, 1.5);
    cm = vis.data.on.fsaverage(morph_data_both=rand_data,
      rglactions=list('no_vis'=T));
    export(cm, colorbar_legend='Random data',
      output_img="~/fsbrain_arranged.png");

## End(Not run)

Export a coloredmeshes with vertexcolors in PLY format.

Description

Exports coloredmeshes with vertex coloring to standard mesh files in Stanford Triangle (PLY) format. This is very hand for rendering in external standard 3D modeling software like Blender.

Usage

export.coloredmesh.ply(filepath, coloredmesh)

Arguments

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   coloredmeshes = vis.subject.morph.native(subjects_dir, 'subject1', 'thickness');
   export.coloredmesh.ply('~/subject1_thickness_lh.ply', coloredmeshed$lh);

## End(Not run)

Recursive computation of neighborhoods, see surf.sphere.dist

Description

Compute neighborhood of the current vertex (=target vertex). The computation follows the mesh edges while there are still vertices which fullfil the dotproduct distance threshold.

Usage

extend_neighbors(
  spherical_surface,
  targetvidx,
  currentvidx,
  min_dotp_thresh,
  ref_visited,
  ref_neighbors,
  ref_neighbor_dpdists
)

Arguments

Value

integer, invisible. Either 0L or 1L. Used in the recursion only, ignore. The return values of interest are in the 3 ref_* parameters.

Try to extract a 3D volume from the input argument.

Description

Check whether it already is such an array, whether it is a filename that can be loaded with freesurferformats::read.fs.volume into such an array, etc.

Usage

extract.volume.3D(stats, silent = getOption("fsbrain.silent", default = FALSE))

Arguments

Value

the obtained 3D array

Note

This function stops with an error if the input cannot be returned as a 3D array.

Enumerate all edges of the given faces or mesh.

Description

Compute edges of a tri-mesh. Can compute all edges, or only a subset, given by the face indices in the mesh.

Usage

face.edges(surface_mesh, face_indices = "all")

Arguments

Value

integer matrix of size (n, 2) where n is the number of edges. The indices (source and target vertex) in each row are **not** sorted, and the edges are **not** unique. I.e., each undirected edge 'u, v' (with the exception of edges on the mesh border) will occur twice in the result: once as 'u, v' and once as 'v, u'.

See Also

Other surface mesh functions: label.border(), mesh.vertex.included.faces(), mesh.vertex.neighbors(), subject.surface(), vis.path.along.verts()

Find the FREESURFER_HOME directory on disk.

Description

Try to find directory containing the FreeSurfer installation, based on environment variables and *educated guessing*.

Usage

find.freesurferhome(mustWork = FALSE)

Arguments

Value

named list with the following entries: "found": logical, whether it was found. "found_at": Only set if found=TRUE, the path to the FreeSurfer installation directory (including the directory itself). See 'mustWork' for important information.

See Also

fs.home

Find the subject directory containing the fsaverage subject (or others) on disk.

Description

Try to find directory containing the fsaverage subject (or any other subject) by checking in the following places and returning the first path where it is found: first, the directory given by the environment variable SUBJECTS_DIR, then in the subir 'subjects' of the directory given by the environment variable FREESURFER_HOME, and finally the base dir of the package cache. See the function download_fsaverage if you want to download fsaverage to your package cache and ensure it always gets found, no matter whether the environment variables are set or not.

Usage

find.subjectsdir.of(subject_id = "fsaverage", mustWork = FALSE)

Arguments

Value

named list with the following entries: "found": logical, whether it was found. "found_at": Only set if found=TRUE, the path to the fsaverage directory (NOT including the fsaverage dir itself). "found_all_locations": list of all locations in which it was found. See 'mustWork' for important information.

See Also

fsaverage.path

Given a list of path coordinates, create matrix containing only the first and last point of each path.

Description

Given a list of path coordinates, create matrix containing only the first and last point of each path.

Usage

flc(coords_list)

Arguments

Value

m x 6 numeric matrix, containing the first and last point of a path per row (two 3D xyz-coords, so 6 values per row).

Change data to ensure requested data_range.

Description

Change data to ensure requested data_range.

Usage

force.to.range(x, data_range, allow_append = FALSE)

Arguments

Value

Modified version of x. The data will be clamped and / or at most 2 values may be appended to x.

Note

This is an artificial modification of the data used for plotting a colormap with a fixed range.

fs.coloredmesh constructor

Description

fs.coloredmesh constructor

Usage

fs.coloredmesh(
  mesh,
  col,
  hemi,
  render = TRUE,
  metadata = NULL,
  add_normals = FALSE
)

Arguments

Value

an ‘fs.coloredmesh' instance. The only fields one should use in client code are ’mesh', 'hemi' and 'col', all others are considered internal and may change without notice.

Return FreeSurfer path.

Description

Return FreeSurfer path.

Usage

fs.home()

Value

the FreeSurfer path, typically what the environment variable 'FREESURFER_HOME' points to.

Note

This function will stop (i.e., raise an error) if the directory cannot be found.

Turn surface mesh into a igraph and return its adjacency list representation.

Description

Turn surface mesh into a igraph and return its adjacency list representation.

Usage

fs.surface.as.adjacencylist(surface)

Arguments

Value

list of integer vectors, the adjacency list.

Create igraph undirected graph from a brain surface mesh.

Description

Create igraph undirected graph from a brain surface mesh.

Usage

fs.surface.to.igraph(surface)

Arguments

Value

igraph::graph instance

Examples

## Not run: 
  # Find the one-ring neighbors of vertex 15 on the fsaverage left hemi:
  sf = subject.surface(fsaverage.path(T), "fsaverage", "white", "lh");
  g = fs.surface.to.igraph(sf);
  igraph::neighborhood(g, order = 1, nodes = 15);

## End(Not run)

Get an rgl tmesh3d instance from a brain surface mesh.

Description

Get an rgl tmesh3d instance from a brain surface mesh.

Usage

fs.surface.to.tmesh3d(surface)

Arguments

Value

a tmesh3d instance, see rgl::tmesh3d for details.

Compute vertex neighborhoods or the full adjacency list for a mesh using the Rvcg or igraph library.

Description

This is a faster replacement for mesh.vertex.neighbors that requires the optional dependency package 'igraph' or 'Rvcg'.

Usage

fs.surface.vertex.neighbors(
  surface,
  nodes = NULL,
  order = 1L,
  simplify = TRUE,
  include_self = FALSE
)

Arguments

Value

named list of integer vectors (see igraph::neighborhood), unless 'simplify' is TRUE, see there for details.

Note

If you intend to call several functions on the igraph, it is faster to construct it with fs.surface.to.igraph and keep it.

See Also

The fs.surface.as.adjacencylist function computes the 1-ring neighborhood for the whole graph.

Create a named value list from a dataframe.

Description

Given the result of the group.agg.atlas.native() function, extract a named region value list (typically for use with the spread.values.over.annot() function) for a single subject.

Usage

fs.value.list.from.agg.res(agg_res, subject_id)

Arguments

Value

region_value_list, named list of strings. Each name must is a region name from the annotation, and the value is a scalar that resulting from aggregating the morphometry data for that region and subject.

Return path to fsaverage dir.

Description

Return path to fsaverage dir.

Usage

fsaverage.path(allow_fetch = FALSE)

Arguments

Value

the path to the fsaverage directory (NOT including the 'fsaverage' dir itself).

Note

This function will stop (i.e., raise an error) if the directory cannot be found. The fsaverage template is part of FreeSurfer, and distributed under the FreeSurfer software license.

Check whether object can be rendered by fsbrain

Description

Check whether object can be rendered by fsbrain

Usage

fsbrain.renderable(x)

Arguments

Value

TRUE if *x* is an instance of a class that can be rendered by fsbrain visualization functions, and FALSE otherwise. Currently, the following types are renderable: 'fs.coloredvoxels', 'fs.coloredmesh', 'Triangles3D'.

See Also

is.Triangles3D

Set default figure size for fsbrain visualization functions.

Description

Set default figure size for fsbrain visualization functions.

Usage

fsbrain.set.default.figsize(width, height, xstart = 50L, ystart = 50L)

Arguments

Note

This function overwrites options("fsbrain.rgloptions"). Output size is limited by your screen resolution. To set your preferred figure size for future R sessions, you could call this function in your '~/.Rprofile' file.

Get subject names from sub directories of FreeSurfer long directory.

Description

Find all subject names for which the FreeSurfer longitudinal pipeline may have finished. These are the subjects that have the _MR1 and _MR2 directories.

Usage

fslong.subjects.detect(subjects_dir, timepoint_names = c("_MR1", "_MR2"))

Arguments

Find completely run FreeSurfer long subjects in a recon-all long output folder.

Description

This finds all subjects for which the FreeSurfer long pipeline finished. It can work without a subjects file, by scanning the directory names to find all potential subjects. It checks only whether the expected folder for each subject exists. For a subject named 'subject1' and 2 timepoints, these folders are checked for existence: subject1, subject1_MR1, subject1_MR2, subject1_MR1.long.subject1, subject1_MR2.long.subject1

Usage

fslong.subjects.finished(
  subjects_dir,
  subjects_to_check = NULL,
  timepoints = seq.int(2)
)

Arguments

Value

a named list with entries 'subjects_okay' and 'subjects_missing_dirs'. Each of these two keys contains a vector of character strings, the respective subjects (a subset if 'subjects_to_check'). In 'subjects_okay' are all subjects for which the expected long directories were found, the rest is in 'subjects_missing_dirs'.

Transform first character of a string to uppercase.

Description

Transform first character of a string to uppercase. This is useful when labeling plots. Important: this function does not know about different encodings, languages or anything, it just calls toupper for the first character.

Usage

fup(word)

Arguments

Value

string, the input string with the first character transformed to uppercase.

Examples

   word_up = fup("word");

Generate test 3D volume of integers. The volume has an outer background area (intensity value 'bg') and an inner foreground areas (intensity value 200L).

Description

Generate test 3D volume of integers. The volume has an outer background area (intensity value 'bg') and an inner foreground areas (intensity value 200L).

Usage

gen.test.volume(vdim = c(256L, 256L, 256L), bg = NA)

Arguments

Value

a 3d array of integers

Note

This function exists for software testing purposes only, you should not use it in client code.

Generate color overlay from geodesic patches around several vertices.

Description

Works across hemispheres (for a whole brain) if you pass a hemilist of meshes as parameter 'mesh', see below.

Usage

geod.patches.color.overlay(
  mesh,
  vertex,
  color = "#FF0000",
  bg_color = "#FEFEFE",
  ...
)

Arguments

Value

vector of color strings (or a hemilist of 2 such vectors if 'mesh' is a hemilist), an overlay suitable for visualization using vis.color.on.subject.

Examples

## Not run: 
  sjd = fsaverage.path(TRUE);
  surfaces = subject.surface(sjd, 'fsaverage', surface = "white", hemi = "both");
  colors = geod.patches.color.overlay(surfaces, vertex = c(12345L, 45L),
    color = c("#FF0000", "#00FF00"), max_distance = 45.0);
  vis.color.on.subject(sjd, 'fsaverage', color_lh=colors$lh, color_rh=colors$rh);

## End(Not run)

Generate color overlay from geodesic patches around several vertices for a single hemi.

Description

Generate color overlay from geodesic patches around several vertices for a single hemi.

Usage

geod.patches.color.overlay.singlehemi(
  mesh,
  vertex,
  color = "#FF0000",
  bg_color = "#FEFEFE",
  ...
)

Arguments

Generate per-vertex distance data from geodesic patches around several vertices.

Description

Works across hemispheres (for a whole brain) if you pass a hemilist of meshes as parameter 'mesh', see below.

Usage

geod.patches.pervertexdata(mesh, vertex, ...)

Arguments

Value

vector of doubles (or a hemilist of 2 such vectors if 'mesh' is a hemilist), the per-vertex distance data. Data for vertices outside neighborhoods will be NA.

Examples

## Not run: 
  sjd = fsaverage.path(TRUE);
  surfaces = subject.surface(sjd, 'fsaverage',
    surface = "white", hemi = "both");
  res = geod.patches.pervertexdata(surfaces,
    vertex = c(12345L, 45L),
    max_distance = 25.0);
  # res$lh and res$rh now hold the per-vertex data.

## End(Not run)

Generate per-vertex distance data from geodesic patches around several vertices for a single hemi.

Description

Generate per-vertex distance data from geodesic patches around several vertices for a single hemi.

Usage

geod.patches.pervertexdata.singlehemi(mesh, vertex, ...)

Arguments

See Also

geod.patches.pervertexdata

Compute all vertices within given geodesic distance on the mesh.

Description

Compute all vertices within given geodesic distance on the mesh.

Usage

geod.vert.neighborhood(
  mesh,
  vertex,
  max_distance = 5,
  include_max = TRUE,
  return_distances = TRUE
)

Arguments

Value

named list with the following entries: 'vertices': integer vector, the indices of all vertices in the neigborhood. 'distances': double vector, the distances to the respective vertices (unless 'return_distances' is FALSE).

Note

This function uses the pseudo-geodesic distance along the mesh edges.

Examples

## Not run: 
  sjd = fsaverage.path(TRUE);
  surface = subject.surface(sjd, 'fsaverage', surface = "white", hemi = "lh");
  res = geod.vert.neighborhood(surface, 12345L, max_distance = 10.0);
  res$vertices;

## End(Not run)

Compute the average (pseudo-) geodesic distance on the mesh from each vertex to all other vertices.

Description

Compute the average (pseudo-) geodesic distance on the mesh from each vertex to all other vertices.

Usage

geodesic.average.distance(surfaces)

Arguments

Note

This may take a while. It requires the 'Rvcg' package.

Compute geodesic ball area and perimeter at location defined by geodists for all radii.

Description

Compute geodesic ball area and perimeter at location defined by geodists for all radii.

Usage

geodesic.ballstats(mesh, geodist, sample_at_radii)

Arguments

Value

named list with entries: 'ball_area': vector of double, ball area at each sample radius. 'ball_perimeter': vector of double, ball perimeter at each sample radius.

Note

This is called from geodesic.circles, there should be no need to call it directly.

Compute geodesic circles and ball stats for given vertices.

Description

Compute geodesic circles and ball stats for given vertices.

Usage

geodesic.circles(surface, vertices = NULL, scale = 5)

Arguments

Note

This takes a while for large meshes, try it with single vertices or with a surface like fsaverage3 if you want it for all vertices. This requires the optional dependency package 'pracma'.

Examples

## Not run: 
  sjd = fsaverage.path(TRUE);
  surface = subject.surface(sjd, 'fsaverage3', hemi='lh');
  gc = geodesic.circles(surface);
  vis.data.on.subject(sjd, 'fsaverage3', morph_data_lh = gc$radius);
  vis.data.on.subject(sjd, 'fsaverage3', morph_data_lh = gc$perimeter);

## End(Not run)

Simple internal wrapper around Rvcg::vcgDijkstra with function check.

Description

Simple internal wrapper around Rvcg::vcgDijkstra with function check.

Usage

geodesic.dists.to.vertex(mesh, v)

Arguments

Value

double vector with length equal to num vertices in the mesh, the geodesic distances from all other vertices to the query vertex v.

Compute geodesic path from a source vertex to one or more target vertices.

Description

Compute geodesic path from a source vertex to one or more target vertices.

Usage

geodesic.path(surface, source_vertex, target_vertices)

Arguments

Value

list of integer vectors, the paths

Note

This can take a bit for very large graphs. This requires the optional dependency package 'Rvcg'. The backtracking is currently done in R, which is not optimal from a performance perspective. If you have a recent Rvcg version with the Rvcg::vcgGeodesicPath function, that one will be used instead, and the performance will be better.

Examples

## Not run: 
  sjd = fsaverage.path(TRUE);
  surface = subject.surface(sjd, 'fsaverage3',
    surface = "white", hemi = "lh");
  p = geodesic.path(surface, 5, c(10, 20));
  vis.subject.morph.native(sjd, 'fsaverage3', 'thickness', views='si');
  vis.paths.along.verts(surface$vertices, p$paths, color=c("red", "yellow"));

## End(Not run)

Determine atlas region names from a subject.

Description

Determine atlas region names from a subject. WARNING: Not all subjects have all regions of an atlas. You should use an average subject like fsaverage to get all regions.

Usage

get.atlas.region.names(
  atlas,
  template_subjects_dir = NULL,
  template_subject = "fsaverage",
  hemi = "lh"
)

Arguments

Value

vector of strings, the region names.

See Also

Other atlas functions: group.agg.atlas.native(), group.agg.atlas.standard(), group.annot(), group.label.from.annot(), label.from.annotdata(), label.to.annot(), regions.to.ignore(), spread.values.over.annot(), spread.values.over.hemi(), spread.values.over.subject(), subject.annot(), subject.atlas.agg(), subject.label.from.annot(), subject.lobes()

Examples

## Not run: 
 fsbrain::download_optional_data();
 subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
 atlas_regions = get.atlas.region.names('aparc',
 template_subjects_dir=subjects_dir, template_subject='subject1');

## End(Not run)

Get the default visualization style parameters as a named list.

Description

Run material3d without arguments to see valid style keywords to create new styles.

Usage

get.rglstyle(style)

Arguments

Value

a style, resolved to a parameter list compatible with material3d.

See Also

shade3d can use the returned style

Get the default visualization style parameters as a named list.

Description

The default rendering style, which is is rather plain. Does not look super fancy, but allows for clear data visualization without distractions. Hint: Run material3d without arguments to see valid style keywords to create new styles.

Usage

get.rglstyle.default()

Value

named list, style parameters that can be passed to shade3d via do.call.

Get the mesh edges visualization style parameters as a named list.

Description

Mesh edges rendering style. Zoom in enough to see them.

Usage

get.rglstyle.edges()

Value

named list, style parameters that can be passed to shade3d via do.call.

Get the glass visualization style parameters as a named list.

Description

Glass-brain rendering style. This style has a very negative impact on rendering performance (especially in interactive mode). Hint: Run material3d without arguments to see valid style keywords to create new styles.

Usage

get.rglstyle.glass()

Value

named list, style parameters that can be passed to shade3d via do.call.

Get the glass2 visualization style parameters as a named list.

Description

Glass-brain rendering style. This style has a very negative impact on rendering performance (especially in interactive mode). Hint: Run material3d without arguments to see valid style keywords to create new styles.

Usage

get.rglstyle.glass2()

Value

named list, style parameters that can be passed to shade3d via do.call.

Produce the named list of style parameters from style definition.

Description

A style definition can be a character string like "shiny", already a parameter list, or a command like 'from_mesh' that tells us to get the style from the renderable. This function creates the final parameters from the definition and the renderable.

Usage

get.rglstyle.parameters(renderable, style)

Arguments

Value

a style, resolved to a parameter list compatible with material3d.

Get the semi-transparent visualization style parameters as a named list.

Description

Semitransparent rendering style. This style has a very negative impact on rendering performance (in interactive mode). Hint: Run material3d without arguments to see valid style keywords to create new styles.

Usage

get.rglstyle.semitransparent()

Value

named list, style parameters that can be passed to shade3d via do.call.

Get a shiny visualization style.

Description

A shiny or glossy rendering style. Looks a bit more modern, but the resulting highlights may make the interpretation of the plotted data a bit harder in some areas. Hint: Run material3d without arguments to see valid style keywords to create new styles.

Usage

get.rglstyle.shiny()

Value

named list, style parameters that can be passed to to shade3d via do.call.

Compute slice indices from slice definition.

Description

Compute slice indices from slice definition.

Usage

get.slice.indices(voldim, axis, slices)

Arguments

Value

integer vector, the computed slice indices. They are guaranteed to be valid indices into the volume.

Construct FSGD Class name from group and non-continuous covariate columns.

Description

Construct FSGD Class name from group and non-continuous covariate columns.

Usage

get.subject.class(demographics_df, row_idx, class_columns, collapse = "_")

Arguments

Value

character string, the Class name for this subject, derived from the values in the 'class_columns'.

Get list of valid view angle names.

Description

The returned strings are used as constants to identify a view of type 'sd_<angle>'. They can be used to construct entries for the parameter 'views' of functions like vis.subject.morph.native, or directly as parameter 'view_angles' for functions like vislayout.from.coloredmeshes.

Usage

get.view.angle.names(angle_set = "all", add_sd_prefix = TRUE)

Arguments

Value

vector of character strings, all valid view angle strings.

Retrieve values from nested named lists

Description

Retrieve values from nested named lists

Usage

getIn(named_list, listkeys, default = NULL)

Arguments

Value

the value at the path through the lists, or ‘NULL' (or the ’default') if no such path exists.

Examples

   data = list("regions"=list("frontal"=list("thickness"=2.3, "area"=2345)));
   getIn(data, c("regions", "frontal", "thickness"));       # 2.3
   getIn(data, c("regions", "frontal", "nosuchentry"));     # NULL
   getIn(data, c("regions", "nosuchregion", "thickness"));  # NULL
   getIn(data, c("regions", "nosuchregion", "thickness"), default=14);  # 14

Access a single file from the package cache by its file name.

Description

Access a single file from the package cache by its file name.

Usage

get_optional_data_filepath(filename, mustWork = TRUE)

Arguments

Value

string. The full path to the file in the package cache or the empty string if there is no such file available. Use this in your application code to open the file.

Aggregate native space morphometry data over brain atlas regions and subjects for a group of subjects.

Description

Aggregate native space morphometry data over brain atlas regions, e.g., compute the mean thickness value over all regions in an atlas for all subjects.

Usage

group.agg.atlas.native(
  subjects_dir,
  subjects_list,
  measure,
  hemi,
  atlas,
  agg_fun = mean,
  cache_file = NULL
)

Arguments

Value

dataframe with aggregated values for all regions and subjects, with n columns and m rows, where n is the number of subjects and m is the number of regions.

See Also

Other aggregation functions: group.agg.atlas.standard(), group.morph.agg.standard.vertex(), subject.atlas.agg()

Other atlas functions: get.atlas.region.names(), group.agg.atlas.standard(), group.annot(), group.label.from.annot(), label.from.annotdata(), label.to.annot(), regions.to.ignore(), spread.values.over.annot(), spread.values.over.hemi(), spread.values.over.subject(), subject.annot(), subject.atlas.agg(), subject.label.from.annot(), subject.lobes()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   agg = group.agg.atlas.native(subjects_dir, c('subject1', 'subject2'),
    'thickness', 'lh', 'aparc');
   # Visualize the mean values. Could use any subject, typically
   # one would use fsaverage. Here we use subject1:
   agg$subject = NULL;   # remove non-numeric column.
   vis.region.values.on.subject(subjects_dir, 'subject1', 'aparc',
    lh_region_value_list=colMeans(agg), rh_region_value_list=NULL);

## End(Not run)

Aggregate standard space morphometry data over brain atlas regions and subjects for a group of subjects.

Description

Aggregate standard space morphometry data over brain atlas regions, e.g., compute the mean thickness value over all regions in an atlas for all subjects.

Usage

group.agg.atlas.standard(
  subjects_dir,
  subjects_list,
  measure,
  hemi,
  atlas,
  fwhm,
  agg_fun = mean,
  template_subject = "fsaverage",
  cache_file = NULL
)

Arguments

Value

dataframe with aggregated values for all regions and subjects, with n columns and m rows, where n is the number of subjects and m is the number of regions.

See Also

Other aggregation functions: group.agg.atlas.native(), group.morph.agg.standard.vertex(), subject.atlas.agg()

Other atlas functions: get.atlas.region.names(), group.agg.atlas.native(), group.annot(), group.label.from.annot(), label.from.annotdata(), label.to.annot(), regions.to.ignore(), spread.values.over.annot(), spread.values.over.hemi(), spread.values.over.subject(), subject.annot(), subject.atlas.agg(), subject.label.from.annot(), subject.lobes()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   agg = group.agg.atlas.standard(subjects_dir, c('subject1', 'subject2'),
    'thickness', 'lh', 'aparc', fwhm='10');
   # Visualize the mean values. Could use any subject, typically
   #  one would use fsaverage. Here we use subject1:
   agg$subject = NULL;   # remove non-numeric column.
   vis.region.values.on.subject(subjects_dir, 'subject1', 'aparc',
    lh_region_value_list=colMeans(agg), rh_region_value_list=NULL);

## End(Not run)

Load annotations for a group of subjects.

Description

Load a brain surface annotation, i.e., a cortical parcellation based on an atlas, for a group of subjects.

Usage

group.annot(subjects_dir, subjects_list, hemi, atlas)

Arguments

Value

list of annotations, as returned by freesurferformats::read.fs.annot(). If hemi is 'both', the annotations are the results of merging over the hemispheres for each subject.

See Also

Other atlas functions: get.atlas.region.names(), group.agg.atlas.native(), group.agg.atlas.standard(), group.label.from.annot(), label.from.annotdata(), label.to.annot(), regions.to.ignore(), spread.values.over.annot(), spread.values.over.hemi(), spread.values.over.subject(), subject.annot(), subject.atlas.agg(), subject.label.from.annot(), subject.lobes()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   subjects_list = c("subject1", "subject2");
   annotations = group.annot(subjects_dir, subjects_list, "lh", "aparc");

## End(Not run)

Concatenate native space data for a group of subjects.

Description

A measure is something like 'thickness' or 'area'. This function concatenates the native space data for all subjects into a single long vector for each measure. A dataframe is then created, in which each column is one such vector. This can be used to compute the correlation between measures on vertex level, for example.

Usage

group.concat.measures.native(
  subjects_dir,
  subjects_list,
  measures,
  hemi,
  cortex_only = FALSE
)

Arguments

Value

dataframe with concatenated vertex values. Each column contains the values for one measure, concatenated for all subjects. WARNING: This dataframe can get large if you have many subjects.

See Also

Other concatination functions: group.concat.measures.standard()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   subjects_list = c('subject1', 'subject2');
   cm = group.concat.measures.native(subjects_dir, subjects_list,
    c("thickness", "area"), "lh");

## End(Not run)

Concatenate standard space data for a group of subjects.

Description

A measure is something like 'thickness' or 'area'. This function concatenates the standard space data for all subjects into a single long vector for each measure. A dataframe is then created, in which each column is one such vector. This can be used to compute the correlation between measures on vertex level, for example.

Usage

group.concat.measures.standard(
  subjects_dir,
  subjects_list,
  measures,
  hemi,
  fwhm_per_measure,
  cortex_only = FALSE
)

Arguments

Value

dataframe with concatenated vertex values. Each column contains the values for one measure, concatenated for all subjects. The column names are a concatination of the measure, "_fwhm", and the fwhm for that measure. WARNING: This dataframe can get large if you have many subjects.

See Also

Other concatination functions: group.concat.measures.native()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   subjects_list = c('subject1', 'subject2');
   cm = group.concat.measures.standard(subjects_dir, subjects_list,
    c("thickness", "area"), "lh", "10");

## End(Not run)

Convert group 2D data (1 vector per subject) to 4D array format.

Description

In general, 1D morphometry data for a group can be stored in a dataframe, a named list, or already a 4D array. This function will convert the given format to 4D array format.

Usage

group.data.to.array(data)

Arguments

Value

the 4D array form of the group data. No values are changed, this is only a different data layout. In neuroimaging, the first 3 dimensions are space, and the 4th is the time/subject dimension.

Examples

    # create per-vertex data for 255 subjects.
    mat = matrix(rnorm(255 * 163842, 3.0, 0.5), nrow=255, ncol = 163842);
    fsbrain:::group.data.to.array(mat);

Retrieve label data for a group of subjects.

Description

Load a label (like 'label/lh.cortex.label') for a group of subjects from disk. Uses knowledge about the FreeSurfer directory structure to load the correct file.

Usage

group.label(
  subjects_dir,
  subjects_list,
  label,
  hemi,
  return_one_based_indices = TRUE
)

Arguments

Value

named list of integer vectors with label data: Each name is a subject identifier from subjects_list, and the values are lists of the vertex indices in the respective label. See 'return_one_based_indices' for important information.

See Also

Other label data functions: labeldata.from.mask(), mask.from.labeldata.for.hemi(), subject.label()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   subjects_list = c("subject1", "subject2");
   labels = group.label(subjects_dir, subjects_list, 'cortex.label', "lh");

## End(Not run)

Extract a region from an atlas annotation as a label for a group of subjects.

Description

The returned label can be used to mask morphometry data, e.g., to set the values of a certain region to NaN or to extract only values from a certain region.

Usage

group.label.from.annot(
  subjects_dir,
  subjects_list,
  hemi,
  atlas,
  region,
  return_one_based_indices = TRUE,
  invert = FALSE,
  error_on_invalid_region = TRUE
)

Arguments

Value

named list of integer vectors with label data: for each subject, the list of vertex indices in the label.

See Also

Other atlas functions: get.atlas.region.names(), group.agg.atlas.native(), group.agg.atlas.standard(), group.annot(), label.from.annotdata(), label.to.annot(), regions.to.ignore(), spread.values.over.annot(), spread.values.over.hemi(), spread.values.over.subject(), subject.annot(), subject.atlas.agg(), subject.label.from.annot(), subject.lobes()

Aggregate native space morphometry data over one hemisphere for a group of subjects.

Description

Compute the mean (or other aggregates) over all vertices of a subject from native space morphometry data (like 'surf/lh.area'). Uses knowledge about the FreeSurfer directory structure to load the correct file.

Usage

group.morph.agg.native(
  subjects_dir,
  subjects_list,
  measure,
  hemi,
  agg_fun = mean,
  cast = TRUE,
  format = "curv",
  cortex_only = FALSE,
  agg_fun_extra_params = NULL
)

Arguments

Value

dataframe with aggregated values for all subjects, with 3 columns and n rows, where n is the number of subjects. The 3 columns are 'subject_id', 'hemi', and '<measure>' (e.g., "thickness"), the latter contains the aggregated data.

See Also

Other global aggregation functions: group.morph.agg.standard(), group.multimorph.agg.native(), group.multimorph.agg.standard()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   subjects_list = c("subject1", "subject2");
   fulldata = group.morph.agg.native(subjects_dir, subjects_list, "thickness", "lh");
   head(fulldata);

## End(Not run)

Aggregate standard space (fsaverage) morphometry data over one hemisphere for a group of subjects.

Description

Compute the mean (or other aggregates) over all vertices of a subject from standard space morphometry data (like 'surf/lh.area.fwhm10.fsaverage.mgh'). Uses knowledge about the FreeSurfer directory structure to load the correct file.

Usage

group.morph.agg.standard(
  subjects_dir,
  subjects_list,
  measure,
  hemi,
  fwhm,
  agg_fun = mean,
  template_subject = "fsaverage",
  format = "mgh",
  cast = TRUE,
  cortex_only = FALSE,
  agg_fun_extra_params = NULL
)

Arguments

Value

dataframe with aggregated values for all subjects, with 2 columns and n rows, where n is the number of subjects. The 2 columns are 'subject_id' and '<hemi>.<measure>' (e.g., "lh.thickness"), the latter contains the aggregated data.

See Also

Other global aggregation functions: group.morph.agg.native(), group.multimorph.agg.native(), group.multimorph.agg.standard()

Aggregate standard space morphometry data over subjects.

Description

Aggregate vertex-wise values over subjects, leading to one aggregated measure per vertex.

Usage

group.morph.agg.standard.vertex(
  subjects_dir,
  subjects_list,
  measure,
  hemi,
  fwhm,
  agg_fun = mean,
  template_subject = "fsaverage",
  format = "mgh",
  cortex_only = FALSE,
  agg_fun_extra_params = NULL,
  split_by_hemi = FALSE
)

Arguments

See Also

Other aggregation functions: group.agg.atlas.native(), group.agg.atlas.standard(), subject.atlas.agg()

Retrieve native space morphometry data for a group of subjects.

Description

Load native space morphometry data (like 'surf/lh.area') for a group of subjects from disk. Uses knowledge about the FreeSurfer directory structure to load the correct file.

Usage

group.morph.native(
  subjects_dir,
  subjects_list,
  measure,
  hemi,
  format = "curv",
  cortex_only = FALSE
)

Arguments

Value

named list with native space morph data, the names are the subject identifiers from the subjects_list, and the values are morphometry data vectors (of different length, as each subject has a different vertex count in native space).

See Also

Other morphometry data functions: apply.label.to.morphdata(), apply.labeldata.to.morphdata(), group.morph.standard(), subject.morph.native(), subject.morph.standard()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   subjects_list = c("subject1", "subject2");
   data = group.morph.native(subjects_dir, subjects_list, "thickness", "lh");

## End(Not run)

Retrieve standard space morphometry data for a group of subjects.

Description

Load standard space morphometry data (like 'surf/lh.area') for a group of subjects from disk. Uses knowledge about the FreeSurfer directory structure to load the correct file.

Usage

group.morph.standard(
  subjects_dir,
  subjects_list,
  measure,
  hemi = "both",
  fwhm = "10",
  template_subject = "fsaverage",
  format = "mgh",
  cortex_only = FALSE,
  df = FALSE,
  df_t = FALSE
)

Arguments

Value

named list with standard space morph data, the names are the subject identifiers from the subjects_list, and the values are morphometry data vectors (all with identical length, the data is mapped to a template subject).

See Also

Other morphometry data functions: apply.label.to.morphdata(), apply.labeldata.to.morphdata(), group.morph.native(), subject.morph.native(), subject.morph.standard()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   subjects_list = c("subject1", "subject2");
   fulldata = group.morph.standard(subjects_dir, subjects_list, "thickness", "lh", fwhm='10');
   mean(fulldata$subject1);

   cortexdata = group.morph.standard(subjects_dir, subjects_list, "thickness",
    "lh", fwhm='10', cortex_only=FALSE);
   mean(cortexdata$subject1, na.rm=TRUE);

## End(Not run)

Read combined data for a group from a single file.

Description

Read morphometry data for a group from a matrix in a single MGH or MGZ file.

Usage

group.morph.standard.sf(filepath, df = TRUE)

Arguments

Value

dataframe or 4d matrix, the morph data. See parameter 'df' for details.

Note

The file has typically been generated by running mris_preproc and/or mri_surf2surf on the command line, or written from R using write.group.morph.standard.sf. The file contains no information on the subject identifiers, you need to know the subjects and their order in the file. Same goes for the hemisphere.

See Also

write.group.morph.standard.mf to write the data to one file per hemi per subject instead. If you have created the input data file in FreeSurfer based on an FSGD file, you can read the subject identifiers from that FSGD file using read.md.subjects.from.fsgd.

Aggregate native space morphometry data for multiple measures over hemispheres for a group of subjects.

Description

Compute the mean (or other aggregates) over all vertices of a subject from native space morphometry data (like 'surf/lh.area'). You can specify several measures and hemispheres. Uses knowledge about the FreeSurfer directory structure to load the correct files.

Usage

group.multimorph.agg.native(
  subjects_dir,
  subjects_list,
  measures,
  hemis,
  agg_fun = mean,
  format = "curv",
  cast = TRUE,
  cortex_only = FALSE,
  agg_fun_extra_params = NULL
)

Arguments

Value

dataframe with aggregated values over all measures and hemis for all subjects, with m columns and n rows, where n is the number of subjects. The m columns are 'subject_id' and '<hemi>.<measure>' (e.g., "lh.thickness") for all combinations of hemi and measure, the latter contains the aggregated data.

See Also

Other global aggregation functions: group.morph.agg.native(), group.morph.agg.standard(), group.multimorph.agg.standard()

Examples

## Not run: 
    subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
    subjects_list = c("subject1", "subject2")
    data = group.multimorph.agg.native(subjects_dir, subjects_list, c("thickness", "area"),
     c("lh", "rh"), cast=FALSE, cortex_only=TRUE, agg_fun=mean,
     agg_fun_extra_params=list("na.rm"=TRUE));
    head(data);

## End(Not run)

Aggregate standard space (fsaverage) morphometry data for multiple measures over hemispheres for a group of subjects.

Description

Compute the mean (or other aggregates) over all vertices of a subject from standard space morphometry data (like 'surf/lh.area.fwhm10.fsaverage.mgh'). You can specify several measures and hemispheres. Uses knowledge about the FreeSurfer directory structure to load the correct files.

Usage

group.multimorph.agg.standard(
  subjects_dir,
  subjects_list,
  measures,
  hemis,
  fwhm,
  agg_fun = mean,
  template_subject = "fsaverage",
  format = "mgh",
  cast = TRUE,
  cortex_only = FALSE,
  agg_fun_extra_params = NULL
)

Arguments

Value

dataframe with aggregated values over all measures and hemis for all subjects, with m columns and n rows, where n is the number of subjects. The m columns are 'subject_id' and '<hemi>.<measure>' (e.g., "lh.thickness") for all combinations of hemi and measure, the latter contains the aggregated data.

See Also

Other global aggregation functions: group.morph.agg.native(), group.morph.agg.standard(), group.multimorph.agg.native()

Retrieve surface mesh data for a group of subjects.

Description

Retrieve surface mesh data for a group of subjects.

Usage

group.surface(
  subjects_dir,
  subjects_list,
  surface,
  hemi = "both",
  force_hemilist = TRUE
)

Arguments

Value

named list of surfaces: Each name is a subject identifier from subjects_list, and the values are hemilists of 'fs.surface' instances.

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   subjects_list = c("subject1", "subject2");
   surfaces = group.surface(subjects_dir, subjects_list, 'white', "both");

## End(Not run)

Split a per-vertex group data matrix for both hemispheres into a hemilist at given index.

Description

Split a per-vertex group data matrix for both hemispheres into a hemilist at given index.

Usage

groupmorph.split.hemilist(data, numverts_lh)

Arguments

Value

hemilist of the data, split at the index.

Examples

## Not run: 
   fsbrain::download_optional_data();
   fsbrain::download_fsaverage(TRUE);
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   subjects_list = c("subject1", "subject2");
   data = group.morph.standard(subjects_dir, subjects_list, "thickness", "lh", fwhm='10');
   numverts_lh = subject.num.verts(subjects_dir, "fsaverage", hemi="lh");
   data_hemilist = groupmorph.split.hemilist(data, numverts_lh);

## End(Not run)

Highlight requested points (if any), but apply given view rotation before doing so.

Description

Highlight requested points (if any), but apply given view rotation before doing so.

Usage

handle.rglactions.highlight.points(
  rglactions,
  angle_rad,
  x,
  y,
  z,
  hemi = "both"
)

Arguments

Check for values in nested named lists

Description

Check for values in nested named lists

Usage

hasIn(named_list, listkeys)

Arguments

Value

whether a non-NULL value exists at the path

Examples

   data = list("regions"=list("frontal"=list("thickness"=2.3, "area"=2345)));
   hasIn(data, c("regions", "nosuchregion"));   # FALSE

Compute lobe labels for a single hemi from aparc atlas.

Description

Compute lobe labels for a single hemi from aparc atlas.

Usage

hemi.lobe.labels(
  subjects_dir,
  subject_id,
  hemi,
  include_cingulate = TRUE,
  as_annot = FALSE
)

Arguments

Note

See subject.lobes for details.

Create a hemilist from lh and rh data.

Description

Simply runs list('lh' = lh_data, 'rh' = rh_data): A hemilist (short for hemisphere list) is just a named list with entries 'lh' and/or 'rh', which may contain anything. Hemilists are used as parameters and return values in many fsbrain functions. The 'lh' and 'rh' keys typically contain surfaces or vectors of morphometry data.

Usage

hemilist(lh_data = NULL, rh_data = NULL)

Arguments

Value

named list, with the 'lh_data' in the 'lh' key and the 'rh_data' in the 'rh' key.

See Also

Other hemilist functions: hemilist.derive.hemi(), hemilist.from.prefixed.list(), hemilist.get.combined.data(), hemilist.unwrap(), hemilist.wrap(), is.hemilist()

Examples

  lh_data = rnorm(163842, 5.0, 1.0);
  rh_data = rnorm(163842, 5.0, 1.0);
  hl = hemilist(lh_data, rh_data);

Derive 'hemi' string from the data in a hemilist

Description

Derive 'hemi' string from the data in a hemilist

Usage

hemilist.derive.hemi(hemilist)

Arguments

Value

character string, one of 'lh', 'rh' or 'both'

Note

See hemilist for details.

See Also

Other hemilist functions: hemilist.from.prefixed.list(), hemilist.get.combined.data(), hemilist.unwrap(), hemilist.wrap(), hemilist(), is.hemilist()

Create a hemilist from a named list with keys prefixed with 'lh_' and 'rh_'.

Description

A hemilist is a named list with entries 'lh' and/or 'rh', see hemilist.

Usage

hemilist.from.prefixed.list(
  named_list,
  report_ignored = TRUE,
  return_ignored = FALSE
)

Arguments

Value

a hemilist

See Also

Other hemilist functions: hemilist.derive.hemi(), hemilist.get.combined.data(), hemilist.unwrap(), hemilist.wrap(), hemilist(), is.hemilist()

Get combined data of hemi list

Description

Get combined data of hemi list

Usage

hemilist.get.combined.data(hemi_list)

Arguments

Value

the data combined with c, or NULL if both entries are NULL.

See Also

Other hemilist functions: hemilist.derive.hemi(), hemilist.from.prefixed.list(), hemilist.unwrap(), hemilist.wrap(), hemilist(), is.hemilist()

Unwrap hemi data from a named hemi list.

Description

Unwrap hemi data from a named hemi list.

Usage

hemilist.unwrap(hemi_list, hemi = NULL, allow_null_list = FALSE)

Arguments

Value

the data

See Also

Other hemilist functions: hemilist.derive.hemi(), hemilist.from.prefixed.list(), hemilist.get.combined.data(), hemilist.wrap(), hemilist(), is.hemilist()

Wrap data into a named hemi list.

Description

Wrap data into a named hemi list.

Usage

hemilist.wrap(data, hemi, hemilist = NULL)

Arguments

Value

a hemilist: a named list, with the 'data' in the name given by parameter 'hemi'

See Also

Other hemilist functions: hemilist.derive.hemi(), hemilist.from.prefixed.list(), hemilist.get.combined.data(), hemilist.unwrap(), hemilist(), is.hemilist()

title Ensure an key for a hemilist exists.

Description

title Ensure an key for a hemilist exists.

Usage

hemlist.ensure.contains(hemilist, required_hemi, error_tag = "")

Arguments

Draw small 3D spheres at given points.

Description

Draw small 3D spheres at given points.

Usage

highlight.points.spheres(coords, color = "#FF0000", radius = 1)

Arguments

See Also

Other 3d utility functions: highlight.vertices.spheres(), vertex.coords()

Highlight vertices given by index on a subject's meshes by coloring faces.

Description

Highlight vertices given by index on a subject's meshes by coloring faces.

Usage

highlight.vertices.on.subject(
  subjects_dir,
  vis_subject_id,
  verts_lh = NULL,
  verts_rh = NULL,
  surface = "white",
  views = c("t4"),
  rgloptions = rglo(),
  rglactions = list(),
  color_bg = "#FEFEFE",
  color_verts_lh = "#FF0000",
  color_verts_rh = "#FF4500",
  k = 0L
)

Arguments

Value

list of coloredmeshes. The coloredmeshes used for the visualization.

See Also

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

Other surface visualization functions: highlight.vertices.on.subject.spheres(), vis.color.on.subject()

Examples

## Not run: 
   fsbrain::download_optional_data();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   highlight.vertices.on.subject(subjects_dir, 'subject1',
     verts_lh=c(5000, 100000), verts_rh=c(300, 66666), views="si");

## End(Not run)

Highlight vertices given by index on a subject's meshes by coloring faces.

Description

Highlight vertices given by index on a subject's meshes by coloring faces.

Usage

highlight.vertices.on.subject.spheres(
  subjects_dir,
  vis_subject_id,
  vertices,
  surface = "white",
  patch_size = 25,
  show_patch = TRUE,
  style = "glass2",
  export_img = NULL,
  sphere_colors = c("#FF0000"),
  sphere_radius = 3,
  ...
)

Arguments

Value

list of coloredmeshes. The coloredmeshes used for the visualization. If export_img is set, the export return value is returned instead.

Note

If no patches are visualized, the color used for the brain can be set with options("fsbrain.brain_na_color"="#FF0000").

See Also

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

Other surface visualization functions: highlight.vertices.on.subject(), vis.color.on.subject()

Examples

## Not run: 
   fsbrain::download_fsaverage(T);
   subjects_dir = fsaverage.path();
   mkco = list('colFn'=viridis::viridis, 'n'=300);
   # Ex.1: highlight with patches and custom colormap:
   highlight.vertices.on.subject.spheres(subjects_dir, 'fsaverage',
     vertices=c(300, 5000, 100000), makecmap_options = mkco);
   # Ex.2: show patches on some (red) vertices, not on blue ones:
   highlight.vertices.on.subject.spheres(subjects_dir, 'fsaverage',
     vertices=c(300, 5000, 100000, 300000), show_patch = c(T,F,T,F),
     sphere_colors = c("red", "blue", "red", "blue"));

## End(Not run)

Draw small 3D spheres at given brain mesh vertices. Supports full brain (2 meshes) as well.

Description

Draw small 3D spheres at given brain mesh vertices. Supports full brain (2 meshes) as well.

Usage

highlight.vertices.spheres(surface, vertices, ...)

Arguments

Note

This function will draw into the current window and add to the scene, so it can be called after visualizing a mesh. See the example.

See Also

Other 3d utility functions: highlight.points.spheres(), vertex.coords()

Examples

## Not run: 
lh_surf = subject.surface('~/data/study1', 'subject1',
 surface = "white", hemi = "lh");
vis.fs.surface(lh_surf, style="semitransparent");
highlight.vertices.spheres(lh_surf,
  vertices = c(3225L, 4300L, 5500L),
  color = c("green", "blue", "red"));

## End(Not run)

Copy the first *n* foreground voxel values.

Description

Copy the first *n* foreground voxel values along the axis and direction from the volume to the hull, thus adding foreground voxels to the hull.

Usage

hull.retain.along.axis(
  volume,
  hull,
  dim_check = 2L,
  upwards = TRUE,
  thickness = 1L
)

Arguments

Value

numeric 3d array, the updated hull volume.

Remap a color in an image, typically used to set the background color to transparent.

Description

Offers 2 algorithm: remap color by flood-filling from a given pixel, or remap a hardcoded color throughout the entire image. Provide one of 'source_color' or 'source_point' by setting the other to NULL. If both are given, source_color takes precedence and source_point is silently ignored.

Usage

## S3 method for class 'remap.color'
image(
  source_img,
  source_color = NULL,
  source_point = "+1+1",
  target_color = "none"
)

Arguments

Annotate image with text.

Description

Annotate image with text.

Usage

images.annotate(images, annotations, do_extend = TRUE, background = "white")

Arguments

Value

vector of magick images, the annotated images

Compute max width and height of magick images.

Description

Compute max width and height of magick images.

Usage

images.dimmax(images)

Arguments

Value

named list with entries 'width' and 'height'

Rescale all images canvas to match the largest one.

Description

Rescale all images canvas to match the largest one.

Usage

images.rescale.to.max.canvas(images, background = "white")

Arguments

Value

vector of magick images, the rescaled images

Extent all images to the height of the image with maximal height.

Description

Extent all images to the height of the image with maximal height.

Usage

images.same.height(images, background_color = "white")

Arguments

Value

a vector/stack of magick images, all with the same height.

Extent all images to the width of the image with maximal width.

Description

Extent all images to the width of the image with maximal width.

Usage

images.same.width(images, background_color = "white")

Arguments

Value

a vector/stack of magick images, all with the same width.

Check whether object is a Triangles3D instance

Description

Check whether object is a Triangles3D instance

Usage

is.Triangles3D(x)

Arguments

Value

TRUE if its argument is a Triangles3D instance (that is, has "Triangles3D" amongst its classes) and FALSE otherwise.

Check whether object is an fs.coloredmesh (S3)

Description

Check whether object is an fs.coloredmesh (S3)

Usage

is.fs.coloredmesh(x)

Arguments

Value

TRUE if its argument is a coloredmesh (that is, has "fs.coloredmesh" amongst its classes) and FALSE otherwise.

Check whether object is an fs.coloredvoxels instance (S3)

Description

Check whether object is an fs.coloredvoxels instance (S3)

Usage

is.fs.coloredvoxels(x)

Arguments

Value

TRUE if its argument is a fs.coloredvoxels instance (that is, has "fs.coloredvoxels" among its classes) and FALSE otherwise.

Check whether object is an fsbrain (S3)

Description

Check whether object is an fsbrain (S3)

Usage

is.fsbrain(x)

Arguments

Value

TRUE if its argument is an fsbrain (that is, has "fsbrain" amongst its classes) and FALSE otherwise.

Check whether x is a hemilist

Description

A hemilist is a named list with entries 'lh' and/or 'rh', see hemilist.

Usage

is.hemilist(x)

Arguments

Value

whether 'x' is a hemilist

See Also

Other hemilist functions: hemilist.derive.hemi(), hemilist.from.prefixed.list(), hemilist.get.combined.data(), hemilist.unwrap(), hemilist.wrap(), hemilist()

Compute border of a label.

Description

Compute the border of a label (i.e., a subset of the vertices of a mesh). The border thickness can be specified. Useful to draw the outline of a region, e.g., a significant cluster on the surface or a part of a ROI from a brain parcellation.

Usage

label.border(
  surface_mesh,
  label,
  inner_only = TRUE,
  expand_inwards = 0L,
  derive = FALSE
)

Arguments

Value

the border as a list with the following entries: 'vertices': integer vector, the vertex indices of the border. Iff the parameter 'derive' is TRUE, the following two additional fields are included: 'edges': integer matrix of size (n, 2) for n edges. Each row defines an edge by its start and target vertex. 'faces': integer vector, the face indices of the border.

See Also

Other surface mesh functions: face.edges(), mesh.vertex.included.faces(), mesh.vertex.neighbors(), subject.surface(), vis.path.along.verts()

Compute border vertices of a label using Rvcg.

Description

Compute border vertices of a label using Rvcg.

Usage

label.border.fast(surface_mesh, label)

Arguments

Value

named list with entry 'vertices' containing an integer vector with the indices of the border vertices.

Note

This is faster than using the label.border function, but it does not fully match its functionality (some parameter are not implemented for this function), and it requires the Rvcg package, which is an optional dependency.

See Also

label.border, which is slower but provides more options and does not require Rvcg.

Examples

## Not run: 
sjd = fsaverage.path(T);
sj = "fsaverage";
mesh = subject.surface(sjd, sj, hemi="lh");
lab = subject.label(sjd, sj, "cortex", hemi = "lh");
col = rep("white", nrow(mesh$vertices));
bd = fsbrain:::label.border.fast <- function(surface_mesh, label);
col[bd$vertices] = "red";
vis.fs.surface(mesh, col=col);

## End(Not run)

A simple colormap function for binary colors.

Description

Useful for plotting labels.

Usage

label.colFn(n = 2L, col_a = "#228B22", col_b = "#FFFFFF")

Arguments

Value

vector of 'n' RGB colorstrings

A simple colormap function for binary colors.

Description

Useful for plotting labels.

Usage

label.colFn.inv(n = 2L, col_a = "#228B22", col_b = "#FFFFFF")

Arguments

Value

vector of 'n' RGB colorstrings

Extract a region from an annotation as a label.

Description

The returned label can be used to mask morphometry data, e.g., to set the values of a certain region to 'NaN' or to extract only values from a certain region.

Usage

label.from.annotdata(
  annotdata,
  region,
  return_one_based_indices = TRUE,
  invert = FALSE,
  error_on_invalid_region = TRUE
)

Arguments

Value

integer vector with label data: the list of vertex indices in the label. See 'return_one_based_indices' for important information.

See Also

Other atlas functions: get.atlas.region.names(), group.agg.atlas.native(), group.agg.atlas.standard(), group.annot(), group.label.from.annot(), label.to.annot(), regions.to.ignore(), spread.values.over.annot(), spread.values.over.hemi(), spread.values.over.subject(), subject.annot(), subject.atlas.agg(), subject.label.from.annot(), subject.lobes()

Merge several labels into an annotation

Description

Merge several labels and a colortable into an annotation.

Usage

label.to.annot(
  label_vertices_by_region,
  num_vertices_in_surface,
  colortable_df = NULL,
  index_of_unknown_region = 1L
)

Arguments

Value

an annotation, see read.fs.annot for details.

See Also

Other atlas functions: get.atlas.region.names(), group.agg.atlas.native(), group.agg.atlas.standard(), group.annot(), group.label.from.annot(), label.from.annotdata(), regions.to.ignore(), spread.values.over.annot(), spread.values.over.hemi(), spread.values.over.subject(), subject.annot(), subject.atlas.agg(), subject.label.from.annot(), subject.lobes()

Examples

  # Create two labels. Real-word labels would have more vertices, of course.
  label1 = c(46666, 467777);
  label2 = c(99888, 99889);
  label_vertices = list("region1"=label1, "region2"=label2);
  colortable_df = data.frame("struct_index"=seq(0, 2),
   "struct_name"=c("unknown", "region1", "region2"),
   "r"=c(255L, 255L, 0L), "g"=c(255L, 0L, 255L), "b"=c(255L, 0L, 0L), "a"=c(0L, 0L, 0L));
  annot = label.to.annot(label_vertices, 100000, colortable_df);

Create labeldata from a mask.

Description

Create labeldata from a mask. This function is trivial and only calls which after performing basic sanity checks.

Usage

labeldata.from.mask(mask, invert = FALSE)

Arguments

Value

labeldata. The list of indices which are TRUE in the mask (or the ones which FALSE if 'invert' is TRUE).

See Also

Other label data functions: group.label(), mask.from.labeldata.for.hemi(), subject.label()

Get data limiting function.

Description

Get data limiting function to use in rglactions as 'trans_fun' to transform data. This is typically used to limit the colorbar in a plot to a certain range. This is similar to clip.data or clip_fun, but uses absolute values instead of percentiles to clip.

Usage

limit_fun(vmin, vmax)

Arguments

Value

a function that takes as argument the data, and clips it to the requested range. I.e., values outside the range will be set to the closest border value ('vmin' or 'vmax'). Designed to be used as rglactions$trans_fun in vis functions, to limit the colorbar and data range.

See Also

rglactions

Examples

   rglactions = list("trans_fun"=limit_fun(2,3));

Get data limiting function to NA.

Description

Get data limiting function to use in rglactions as 'trans_fun' to transform data. This is typically used to limit the colorbar in a plot to a certain range. This is similar to clip.data, but uses absolute values instead of percentiles to clip.

Usage

limit_fun_na(vmin, vmax)

Arguments

Value

a function that takes as argument the data, and clips it to the requested range. I.e., values outside the range will be set to 'NA'. Designed to be used as rglactions$trans_fun in vis functions, to limit the colorbar and data range.

Note

This is useful for thresholding stuff like t-value maps. All values outside the range will be displayed as the background color.

See Also

limit_fun_na_inside which will set the values inside the range to 'NA'.

Examples

   rglactions = list("trans_fun"=limit_fun_na(2,3));

Get data limiting function, setting values inside range to NA.

Description

Get data limiting function to use in rglactions as 'trans_fun' to transform data.

Usage

limit_fun_na_inside(vmin, vmax)

Arguments

Value

a function that takes as argument the data, and clips it to the requested range. I.e., values inside the range will be set to 'NA'. Designed to be used as rglactions$trans_fun in vis functions.

Note

This is useful for thresholding data plotted with a background. All values inside the range will set to NA and be transparent, and thus be displayed as the background color.

See Also

limit_fun_na which will set the values outside the range to 'NA'.

Examples

   rglactions = list("trans_fun"=limit_fun_na_inside(2,3));

Get file names available in package cache.

Description

Get file names of optional data files which are available in the local package cache. You can access these files with get_optional_data_file().

Usage

list_optional_data()

Value

vector of strings. The file names available, relative to the package cache.

Arrange a multi-frame ImageMagick image into a grid.

Description

Arrange all subimages of the given ImageMagick image into a single 2D image, that contains the subimages arranged in a grid-like structure. Consecutive subimages will be appear the same row.

Usage

magick.grid(
  magickimage,
  per_row = 5L,
  per_col = NULL,
  background_color = "#000000"
)

Arguments

Create a binary mask from labels.

Description

Create a binary mask for the data of a single hemisphere from one or more labels. A label contains the vertex indices which are part of it, but often having a mask in more convenient.

Usage

mask.from.labeldata.for.hemi(
  labels,
  num_vertices_in_hemi,
  invert_labels = FALSE,
  existing_mask = NULL
)

Arguments

Value

logical vector. The mask. It contains a logical value for each vertex. By default, the vertex indices from the labels are FALSE and the rest are TRUE, but this can be changed with the parameter 'invert_labels'.

See Also

Other label data functions: group.label(), labeldata.from.mask(), subject.label()

Other mask functions: coloredmesh.from.mask(), vis.mask.on.subject()

Examples

## Not run: 
   fsbrain::download_optional_data();

  # Define the data to use:
  subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
  subject_id = 'subject1';
  surface = 'white';
  hemi = 'both';
  atlas = 'aparc';
  region = 'bankssts';

  # Create a mask from a region of an annotation:
  lh_annot = subject.annot(subjects_dir, subject_id, 'lh', atlas);
  rh_annot = subject.annot(subjects_dir, subject_id, 'rh', atlas);
  lh_label = label.from.annotdata(lh_annot, region);
  rh_label = label.from.annotdata(rh_annot, region);
  lh_mask = mask.from.labeldata.for.hemi(lh_label, length(lh_annot$vertices));
  rh_mask = mask.from.labeldata.for.hemi(rh_label, length(rh_annot$vertices));

  # Edit the mask: add the vertices from another region to it:
  region2 = 'medialorbitofrontal';
  lh_label2 = label.from.annotdata(lh_annot, region2);
  rh_label2 = label.from.annotdata(rh_annot, region2);
  lh_mask2 = mask.from.labeldata.for.hemi(lh_label2, length(lh_annot$vertices),
   existing_mask = lh_mask);
  rh_mask2 = mask.from.labeldata.for.hemi(rh_label2, length(rh_annot$vertices),
   existing_mask = rh_mask);

## End(Not run)

Merge the annotations from two hemispheres into one annot.

Description

Merge the annotations from two hemispheres into one annot.

Usage

mergehemi.annots(lh_annot, rh_annot)

Arguments

Value

annot, the merged annotation.

Return all faces which are made up completely of the listed vertices.

Description

Return all faces which are made up completely of the listed vertices.

Usage

mesh.vertex.included.faces(surface_mesh, source_vertices)

Arguments

Value

integer vector, the face indices

See Also

Other surface mesh functions: face.edges(), label.border(), mesh.vertex.neighbors(), subject.surface(), vis.path.along.verts()

Compute neighborhood of a vertex

Description

Given a set of query vertex indices and a mesh *m*, compute all vertices which are adjacent to the query vertices in the mesh. A vertex *u* is *adjacent* to another vertex *v* iff there exists an edge *e = (u, v)* in *m*. While you could call this function repeatedly with the old output as its new input to extend the neighborhood, you should maybe use a proper graph library for this.

Usage

mesh.vertex.neighbors(
  surface,
  source_vertices,
  k = 1L,
  restrict_to_vertices = NULL
)

Arguments

Value

the neighborhood as a list with two entries: "faces": integer vector, the face indices of all faces the source_vertices are a part of. "vertices": integer vector, the unique vertex indices of all vertices of the faces in the 'faces' property. These vertex indices include the indices of the source_vertices themselves.

See Also

Other surface mesh functions: face.edges(), label.border(), mesh.vertex.included.faces(), subject.surface(), vis.path.along.verts()

Return recommended 'makecmap_options' for diverging cluster data.

Description

This function returns recommended visualization settings (a colormap function and suitable other settings) for the given type of data. The return value is meant to be passed as parameter 'makecmap_options' to the vis.* functions, e.g., vis.subject.morph.native.

Usage

mkco.cluster()

Value

named list, visualization settings to be used as 'makecmap_options' for diverging data.

Note

This uses a cyan blue red yellow colormap, which is popular for displaying clusters in neuroscience.

Return recommended 'makecmap_options' for diverging data.

Description

This function returns recommended visualization settings (a colormap function and suitable other settings) for the given type of data. The return value is meant to be passed as parameter 'makecmap_options' to the vis.* functions, e.g., vis.subject.morph.native.

Usage

mkco.div()

Value

named list, visualization settings to be used as 'makecmap_options' for diverging data.

Return recommended 'makecmap_options' for sequential data with heatmap style.

Description

This function returns recommended visualization settings (a colormap function and suitable other settings) for the given type of data. The return value is meant to be passed as parameter 'makecmap_options' to the vis.* functions, e.g., vis.subject.morph.native.

Usage

mkco.heat()

Value

named list, visualization settings to be used as 'makecmap_options' for sequential data with heatmap style.

Return recommended 'makecmap_options' for sequential data.

Description

This function returns recommended visualization settings (a colormap function and suitable other settings) for the given type of data. The return value is meant to be passed as parameter 'makecmap_options' to the vis.* functions, e.g., vis.subject.morph.native.

Usage

mkco.seq()

Value

named list, visualization settings to be used as 'makecmap_options' for sequential data.

Normalize data.

Description

Scales data to the range '[0, 1]' based on min and max values.

Usage

normalize(x)

Arguments

Value

the scaled data

Determine vertex count of left hemi from hemilist of surfaces or the count itself.

Description

Determine vertex count of left hemi from hemilist of surfaces or the count itself.

Usage

numverts.lh(surfaces)

Arguments

Value

integer, the number of vertices.

Determine vertex count of right hemi from hemilist of surfaces or the count itself.

Description

Determine vertex count of right hemi from hemilist of surfaces or the count itself.

Usage

numverts.rh(surfaces)

Arguments

Value

integer, the number of vertices.

Compute path color from its orientation.

Description

Compute path color from its orientation.

Usage

path.colors.from.orientation(coords_list, use_three_colors_only = FALSE)

Arguments

Value

m x 3 matrix, each row corresponds to a path and contains its color value (RGB, range 0..255).

Compute slopes of paths relative to axes.

Description

Compute slopes of paths relative to axes.

Usage

path.slopes(coords_list, return_angles = FALSE)

Arguments

Value

m x 3 matrix, each row corresponds to a path and describes the 3 slopes of the path against the 3 planes/ x, y, and z axes (in that order).

Transform surfaces indices which go over two surfaces to per-hemi indices.

Description

Transform surfaces indices which go over two surfaces to per-hemi indices.

Usage

per.hemi.vertex.indices(surfaces, vertices)

Arguments

Value

named list with the following entries: 'vertices', hemilist of indices for the hemispheres. 'query_indices', hemilist of the indices of the respective vertices in the vector that was passed as parameter vertices. 'vertices_hemi': vector of character strings containing the hemi value (lh or rh) for the query vertices.

Perform NA mapping for transparency

Description

Usually this is done so that the 'NA' values are plotted transparently, so your can see a background color through the respective colors.

Usage

perform.na.mapping(data, map_to_NA)

Arguments

Value

the mapped data

Perform rglactions, like taking screenshots.

Description

Take a list specifying actions, see rglactions, and execute them. This function should be called once an rgl scene has been setup and rendered. A typical use case is to save a screenshot of the scene.

Usage

perform.rglactions(rglactions, at_index = NULL, silent = TRUE, ignore = c())

Arguments

Perform Gaussian smoothing

Description

Perform Gaussian smoothing

Usage

pervertexdata.smoothgaussian(
  spherical_surface,
  data,
  fwhm = 15,
  truncfactor = 3.5
)

Arguments

Value

the smoothed data

Note

This function has been adapted from FreeSurfer and it is subject to the FreeSurfer software license.

Examples

## Not run: 
sjd = fsaverage.path();
spherical_surface = subject.surface(sjd, "fsaverage3",
  surface="sphere", hemi="lh");
vdata = subject.morph.native(sjd, "fsaverage3", "thickness", hemi="lh");
vdata_smoothed = pervertexdata.smoothgaussian(spherical_surface,
 vdata, fwhm = 15);
vis.data.on.subject(sjd, "fsaverage3", morph_data_lh = vdata);
vis.data.on.subject(sjd, "fsaverage3", morph_data_lh = vdata_smoothed);

## End(Not run)

Perform iterative nearest-neighbor smoothing of per-vertex data.

Description

Smoothing of surface data by iterative mesh neighborhood averaging. Assigns to each vertex the average of the values in its 1-ring neighborhood (based on the mesh edges).

Usage

pervertexdata.smoothnn(surface, data, num_iter, k = 1L)

Arguments

Note

The iteration is currently done in R, which means the performance is not great.

This does NOT smooth the mesh, it smoothes per-vertex values assigned to mesh vertices.

To see relevant smoothing for full-resolution FreeSurfer meshes, try setting num_iter=50, k=8 for a start.

Examples

## Not run: 
sjd = fsaverage.path(T);
sj = "fsaverage3";
surface = subject.surface(sjd, sj, hemi = "lh");
th = subject.morph.native(sjd, sj, "thickness", hemi="lh", cortex_only=T);
th_smooth = pervertexdata.smoothnn(surface, th, num_iter=15L);
vis.data.on.subject(sjd, sj, morph_data_lh = th);
vis.data.on.subject(sjd, sj, morph_data_lh = th_smooth);

## End(Not run)

Compute expected FWHM from given number of neighborhood smoothing iterations.

Description

Compute expected FWHM from given number of neighborhood smoothing iterations.

Usage

pervertexdata.smoothnn.compute.fwhm(surface, niters, is_template)

Arguments

Value

double, the expected FWHM

Note

This function has been adapted from FreeSurfer and it is subject to the FreeSurfer software license.

Examples

## Not run: 
spherical_surface = subject.surface(fsaverage.path(), "fsaverage3", surface="sphere", hemi="lh");
fsbrain:::pervertexdata.smoothnn.compute.fwhm(spherical_surface, 5L);

## End(Not run)

Compute number of neighborhood smoothing iterations to reach requested fwhm.

Description

Compute number of neighborhood smoothing iterations to reach requested fwhm.

Usage

pervertexdata.smoothnn.compute.numiter(surface, fwhm, is_template)

Arguments

Value

integer, the iteration count

Note

This function has been adapted from FreeSurfer and it is subject to the FreeSurfer software license.

Draw a simple colorbar from colors.

Description

Draw a simple colorbar from colors.

Usage

## S3 method for class 'fsbrain.colorbar'
plot(colors, horizontal = FALSE)

Arguments

Note

This function assumes that there is an open plot, use plot.new() to create one before calling this function if that is not the case.

Pretty-print a named list or vector.

Description

Pretty-print a named list or vector.

Usage

pp.named.list(named_list)

Arguments

Value

character string, the printed list

Computes principal curvatures according to 2 definitions from raw k1 and k2 values.

Description

Computes principal curvatures according to 2 definitions from raw k1 and k2 values.

Usage

principal.curvatures(k1_raw, k2_raw)

Arguments

Value

a named 'principal_curvatures' list, with entries 'principal_curvature_k1': larger value of k1_raw, k2_raw. 'principal_curvature_k2': smaller value of k1_raw, k2_raw. 'principal_curvature_k_major': larger value of abs(k1_raw), abs(k2_raw). 'principal_curvature_k_minor': smaller value of abs(k1_raw), abs(k2_raw).

Note

To obtain k1_raw and k2_raw, use surface.curvatures to compute it from a mesh, or load the FreeSurfer files 'surf/?h.white.max' and 'surf/?h.white.min'.

Print description of a brain coloredmesh (S3).

Description

Print description of a brain coloredmesh (S3).

Usage

## S3 method for class 'fs.coloredmesh'
print(x, ...)

Arguments

Print description of fs.coloredvoxels (S3).

Description

Print description of fs.coloredvoxels (S3).

Usage

## S3 method for class 'fs.coloredvoxels'
print(x, ...)

Arguments

Print description of an fsbrain (S3).

Description

Print description of an fsbrain (S3).

Usage

## S3 method for class 'fsbrain'
print(x, ...)

Arguments

Perform data quality check based on computed region stats.

Description

Determine subjects that potentially failed segmentation, based on region-wise morphometry data. The stats can be computed from any kind of data, but something like area or volume most likely works best. The stats are based on the mean of the region values, so the measure should at least roughly follow a normal distribution.

Usage

qc.for.group(subjects_dir, subjects_list, measure, atlas, hemi = "both", ...)

Arguments

Value

qc result as a hemilist, each entry contains a named list as returned by qc.from.regionwise.df.

See Also

Other quality check functions: qc.from.regionwise.df(), qc.from.segstats.table()

Perform data quality check based on a dataframe containing aggregated region-wise data.

Description

Determine subjects that potentially failed segmentation, based on region-wise data. The data can be anything, but there must be one numerical value per subject per region.

Usage

qc.from.regionwise.df(
  rdf,
  z_threshold = 2.8,
  verbosity = 0L,
  num_bad_regions_allowed = 1L
)

Arguments

Value

named list with entries: 'failed_subjects': vector of character strings, the subject identifiers which potentially failed segmentation. 'mean_dists_z': distance to mean, in standard deviations, per subject per region. 'num_outlier_subjects_per_region': number of outlier subjects by region. 'metadata': named list of metadata, e.g., hemi, atlas and measure used to compute these QC results.

See Also

Other quality check functions: qc.for.group(), qc.from.segstats.table()

Perform data quality check based on a segstats table.

Description

Perform data quality check based on a segstats table.

Usage

qc.from.segstats.table(filepath, ...)

Arguments

Value

see qc.from.regionwise.df

See Also

Other quality check functions: qc.for.group(), qc.from.regionwise.df()

Perform data quality check based on a segstats table.

Description

Determine subjects that potentially failed segmentation, based on segstats table data. The input table file must be a segmentation or parcellation table, generated by running the FreeSurfer tools 'aparcstats2table' or 'asegstats2table' for your subjects.

Usage

qc.from.segstats.tables(filepath_lh, filepath_rh, ...)

Arguments

Value

qc result as a hemilist, each entry contains a named list as returned by qc.from.regionwise.df.

Check whether subjects for FS longitudinal pipeline contain data that is identical between time points.

Description

Check whether subjects for FS longitudinal pipeline contain data that is identical between time points.

Usage

qc.fslong.checkidenticaldata(
  subjects_dir,
  subjects_to_check = NULL,
  timepoint_names = c("_MR1", "_MR2"),
  measure = "thickness",
  surface = "white"
)

Arguments

Note

Keep in mind that this checks on the level of the FreeSurfer reconstruction, which is not 100

Create visual quality check report from QC result.

Description

Create visual quality check report from QC result.

Usage

qc.report.html(
  subjects_dir,
  subjects_list,
  out_dir = "fsbrain_qc_report",
  subjects_metadata = list(),
  qc = NULL,
  ...
)

Arguments

Examples

## Not run: 
s = sjld("~/data/IXI_min/mri/freesurfer");
s$l = s$l[1:100]; # first few subjects are enough
fsbrain:::qc.report.html(s$d, s$l);

## End(Not run)

Visualize the number of outlier subjects per region in your dataset.

Description

The function helps you to see which regions are affected the most by QC issues: for each region, it plots the number of subjects which are outliers in the region.

Usage

qc.vis.failcount.by.region(
  qc_res,
  atlas,
  subjects_dir = fsaverage.path(),
  subject_id = "fsaverage",
  ...
)

Arguments

Note

You can visualize this on any subject you like, 'fsaverage' is a typical choice. The atlas must be the one used during the QC step.

Filter QDEC long table for subjects.

Description

Filter QDEC long table for subjects.

Usage

qdec.table.filter(qdec_file, subjects_list, output_qdec_file = NULL)

Arguments

Value

the data.frame containing the subset of subjects from the original QDEC file.

Note

This assumes that there are 2 time points per subject and warns if not all requested subjects were found.