Package {fsbrain}

Type:	Package
Title:	Managing and Visualizing Brain Surface Data
Version:	1.0.0
Maintainer:	Tim Schäfer <ts+code@rcmd.org>
Description:	Provides high-level access to neuroimaging data from standard software packages like 'FreeSurfer' https://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
Copyright:	Tim Schäfer (package code); the optional data files that can be downloaded at runtime are owned by their respective copyright holders, see 'inst/COPYRIGHTS'.
Encoding:	UTF-8
URL:	https://github.com/dfsp-spirit/fsbrain
BugReports:	https://github.com/dfsp-spirit/fsbrain/issues
Imports:	freesurferformats (≥ 1.1.0), pkgfilecache (≥ 0.4.1), rgl, squash, fields, viridis, magick, methods
Suggests:	knitr, rmarkdown, scimesh (≥ 0.4.0), testthat (≥ 2.1.0), misc3d, oro.nifti, RColorBrewer, Rvcg (≥ 0.20.2), igraph, pracma, withr
VignetteBuilder:	knitr
Config/roxygen2/version:	8.0.0
RoxygenNote:	7.3.3
NeedsCompilation:	no
Packaged:	2026-09-26 18:26:55 UTC; ts
Author:	Tim Schäfer [aut, cre], The General Hospital Corporation (Boston, MA) [cph] (Copyright holder of FreeSurfer and thus the fsaverage template subject that can OPTIONALLY be downloaded via fsbrain functions.), Van Essen Lab [cph] (Copyright holder of the fs_LR 32k template that can OPTIONALLY be downloaded via fsbrain functions.), Alexander Schaefer [cph] (Copyright holder of the Schaefer 100-1000 atlases that can OPTIONALLY be downloaded via fsbrain functions.), Ru Kong [cph] (Copyright holder of the Brainnetome atlas that can OPTIONALLY be downloaded via fsbrain functions.), Lingzhong Fan [cph] (Copyright holder of the AAL3 atlas that can OPTIONALLY be downloaded via fsbrain functions.), Edmund T. Rolls [cph] (Copyright holder of the HCP-MMP1 atlas that can OPTIONALLY be downloaded via fsbrain functions.), Matthew F. Glasser [cph] (Copyright holder of the HCP-MMP1 atlas that can OPTIONALLY be downloaded via fsbrain functions.), Kathryn Mills [cph] (Provided the conversion of the HCP-MMP1 atlas to fsaverage space that can OPTIONALLY be downloaded via fsbrain functions.)
Repository:	CRAN
Date/Publication:	2026-09-26 20:40:02 UTC

The default anti-aliasing factor of the scimesh backend

Description

The anti-aliasing factor used for scimesh renders when neither the fsbrain option 'fsbrain.scimesh.aa_samples' nor the scimesh-wide option 'scimesh.aa_samples' is set. scimesh renders without anti-aliasing by default, which is most visible on thin lines (they show a staircase pattern, unlike the hardware-drawn lines of the rgl backend), so fsbrain requests 2x2 supersampling. Set 'fsbrain.scimesh.aa_samples' to 1 to turn anti-aliasing off, or to 4 for higher quality.

Usage

FSBRAIN_SCIMESH_DEFAULT_AA

Convert a misc3d Triangles3D iso-surface to a coloredmesh.

Description

Convert a misc3d::contour3d(draw = FALSE) result (an iso-surface mesh of class 'Triangles3D', e.g., as returned by volvis.contour) into an fs.coloredmesh. This allows rendering volume iso-surfaces with ANY renderer backend: while the rgl backend can render 'Triangles3D' instances directly, the scimesh backend requires fs.coloredmesh instances and converts them automatically, so you normally do not need to call this function yourself.

Usage

Triangles3D.to.coloredmesh(tris, hemi = NULL, add_normals = TRUE)

Arguments

Value

an fs.coloredmesh instance, or a list of such instances if 'tris' is a list.

See Also

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

Reshape aggregated region data from long to wide format.

Description

Internal helper. Takes a long-format dataframe with one row per subject and atlas region (as returned by subject.atlas.agg) and reshapes it into a wide dataframe with one row per subject and one column per atlas region, plus a leading character column named 'subject' which holds the subject identifiers. Region columns are sorted alphabetically. Cells for which no data is available are set to NA.

Usage

agg.res.long.to.wide(agg_all_subjects, subjects_list, agg_fun = NULL)

Arguments

Value

dataframe in wide format, with one row per subject. The first column is named 'subject' and holds the subject identifiers, the remaining columns are named after the atlas regions and hold the aggregated values.

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.

Apply a 4x4 affine matrix to vertex coordinates.

Description

Internal helper, applies the matrix to homogeneous column vectors, i.e., ⁠v' = M %*% v⁠.

Usage

apply.affine.to.coords(coords, affine_matrix)

Arguments

Value

Nx3 matrix of transformed coordinates.

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()

Extract the alpha value from resolved style parameters

Description

Extract the alpha value from resolved style parameters

Usage

apply.style.alpha(style_params)

Arguments

Value

numeric scalar alpha in 0..1, defaults to 1 (opaque) if not set.

Apply affine transformation to input.

Description

Apply an affine transformation, like a vox2ras_tkr transformation, to input. This is just matrix multiplication for different input objects. Supported input types are coordinate vectors, coordinate matrices, fs.surface meshes (the vertex coordinates are transformed, the face indices stay the same), renderable objects like fs.coloredmesh, fs.coloredvoxels, fs.coloredpaths or misc3d Triangles3D, rgl mesh3d/tmesh3d instances (including their normals, if any), and (hemi-)lists of such objects (which are transformed element-wise).

Usage

apply.transform(object, matrix_fun)

Arguments

Value

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

Note

The affine matrix is applied in the standard way: the coordinates are interpreted as homogeneous column vectors, i.e., a vertex v is transformed as ⁠v' = M %*% v⁠. Note that rgl, and fsbrain functions that are implemented on top of rgl (like the camera transforms used internally for views), use the transposed convention for their rotation matrices, see rotationMatrix. For pure translations and scalings, both conventions are identical.

Meshes keep their orientation: if the linear part of the matrix has a negative determinant, the transformation mirrors the object (this is the case for the FreeSurfer vox2ras_tkr matrix, which flips and permutes axes), which would invert all surface normals and make the mesh render inside-out. In that case, the vertex order within each face is reversed to preserve the original orientation, and the stored normals (if any) are transformed with the linear part of the matrix so that they stay consistent with the faces.

Examples

## Not run: 
   # Transform the vertex coordinates of a surface mesh:
   cube_file = system.file("extdata", "cube.ply", package = "fsbrain");
   cube = freesurferformats::read.fs.surface(cube_file);
   translation = matrix(c(1,0,0,10, 0,1,0,20, 0,0,1,30, 0,0,0,1), nrow = 4L, byrow = TRUE);
   cube_moved = apply.transform(cube, translation);

## End(Not run)

Apply an affine transformation matrix to an object.

Description

Internal workhorse of apply.transform, assumes that the matrix has already been resolved from the 'matrix_fun' parameter.

Usage

apply.transform.matrix(object, affine_matrix)

Arguments

Value

the transformed object.

Apply a 4x4 transformation matrix to tracts.

Description

Apply a 4x4 transformation matrix to tracts.

Usage

apply.transform.to.tracts(tracts, transform_matrix)

Arguments

Value

the fs.tracts instance with transformed coordinates.

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'.

Turn the various supported tract inputs into a list of bundles.

Description

Turn the various supported tract inputs into a list of bundles.

Usage

as.tract.bundle.list(
  tracts,
  coords = "ras",
  transform_matrix = NULL,
  max_tracks = Inf,
  skip_tracks = 0L,
  bbox = NULL,
  silent = FALSE
)

Arguments

Value

named list of fs.tracts instances.

Compute the bounding sphere of a set of 3D vertices.

Description

Computes the sphere that encloses the axis-aligned bounding box (AABB) of the given vertices, using the same convention as rgl's Sphere(AABB) auto-framing (see rgl src/geom.cpp) and scimesh's camera_auto(rgl_compat=TRUE): the center is the AABB center and the radius is half the length of the AABB diagonal.

Usage

bounding_sphere(vertices)

Arguments

Value

a list with entries center (numeric vector of length 3) and radius (numeric scalar). For an empty/zero-extent input, radius is 0 and the center is the single vertex (or NA if no vertices).

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

Check whether a matrix is a valid point matrix for coloredpaths.

Description

Check whether a matrix is a valid point matrix for coloredpaths.

Usage

check.segment.points(x, arg_name)

Arguments

Value

an (n, 3) numeric matrix.

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.

Check a transformation matrix.

Description

Check a transformation matrix.

Usage

check.transform.matrix(transform_matrix)

Arguments

Value

the matrix, as a 4x4 numeric matrix.

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));

Compute the alpha value of a cluster shell.

Description

The shells of a cluster are more transparent the closer they are to the threshold, and fully opaque at the highest level of their sign.

Usage

cluster.shell.alpha(level, threshold, levels, alpha_range = c(0.08, 1))

Arguments

Value

single number between 0 and 1, the alpha value of the shell.

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.annot(), collayer.from.annotdata(), 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(), collayer.bg.meancurv(), collayer.bg.sulc(), collayer.from.annot(), collayer.from.annotdata(), 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(), collayer.bg.atlas(), collayer.bg.sulc(), collayer.from.annot(), collayer.from.annotdata(), 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(), collayer.bg.atlas(), collayer.bg.meancurv(), collayer.from.annot(), 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.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(), collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg.sulc(), 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(), collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg.sulc(), 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(), collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg.sulc(), collayer.from.annot(), collayer.from.annotdata(), 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(), collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg.sulc(), collayer.from.annot(), collayer.from.annotdata(), 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(), collayer.bg.atlas(), collayer.bg.meancurv(), collayer.bg.sulc(), collayer.from.annot(), collayer.from.annotdata(), collayer.from.mask.data(), collayer.from.morphlike.data()

Convert an R color to an RGBA float vector

Description

Converts an R color specification (hex string like "#FF0000", color name like "white", or "#FF0000FF") to a length-4 RGBA numeric vector with values in the range 0..1.

Usage

color_to_rgba(color)

Arguments

Value

numeric vector of length 4, RGBA values in 0..1 range.

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: Triangles3D.to.coloredmesh(), coloredmesh.from.color(), 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(),
  style = NULL
)

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'. If not NULL, also "style": the rendering style for this mesh.

Note

You will usually not call this directly, but use coloredmeshes.from.color or vis.color.on.subject instead. It is exported for cases in which you want to build a single hemisphere of a scene manually.

See Also

Other coloredmesh functions: Triangles3D.to.coloredmesh(), coloredmesh.from.annot(), 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 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: Triangles3D.to.coloredmesh(), coloredmesh.from.annot(), coloredmesh.from.color(), 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: Triangles3D.to.coloredmesh(), coloredmesh.from.annot(), coloredmesh.from.color(), 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: Triangles3D.to.coloredmesh(), coloredmesh.from.annot(), coloredmesh.from.color(), 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: Triangles3D.to.coloredmesh(), coloredmesh.from.annot(), coloredmesh.from.color(), 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: Triangles3D.to.coloredmesh(), coloredmesh.from.annot(), coloredmesh.from.color(), 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

Create a coloredmesh that draws a set of spheres (e.g., connectome nodes).

Description

Builds one mesh containing all spheres, with a per-vertex color taken from the color of the sphere the vertex belongs to. The result is a regular fs.coloredmesh instance, so it can be rendered, transformed and exported like any other mesh. Note that the vertices of a sphere are not shared with any other sphere, so each sphere can have its own radius and color.

Usage

coloredmesh.from.spheres(
  centers,
  radii = 1,
  col = "#FF0000",
  subdivisions = 2L,
  metadata = list(),
  hemi = NULL,
  style = NULL
)

Arguments

Value

fs.coloredmesh instance.

Examples

  centers = rbind(c(0, 0, 0), c(10, 0, 0));
  cm = fsbrain:::coloredmesh.from.spheres(centers, c(1, 2), c("#FF0000", "#00FF00"));
  class(cm);

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)

Convert a single fs.coloredmesh to a scimesh mesh descriptor

Description

Convert a single fs.coloredmesh to a scimesh mesh descriptor

Usage

coloredmesh_to_scimesh(cmesh, style = "default")

Arguments

Value

a scimesh mesh descriptor list with vertices, triangles, and colors.

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(),
  style = NULL
)

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'. If not NULL, also "style": the rendering style for the mesh.

See Also

Other coloredmesh functions: Triangles3D.to.coloredmesh(), coloredmesh.from.annot(), coloredmesh.from.color(), 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

Convert a hemilist of fs.coloredmeshes to a list of scimesh mesh descriptors

Description

Convert a hemilist of fs.coloredmeshes to a list of scimesh mesh descriptors

Usage

coloredmeshes_to_scimesh(coloredmeshes, style = "default")

Arguments

Value

a named list of scimesh mesh descriptors, with the same hemilist structure. Only meshes with render=TRUE are included.

Get the number of segments of an fs.coloredpaths instance.

Description

Get the number of segments of an fs.coloredpaths instance.

Usage

coloredpaths.length(x)

Arguments

Value

positive integer, the number of segments.

Convert an fs.coloredpaths instance to scimesh line layers

Description

Line segments have no mesh representation, so they cannot be passed to the scimesh renderer as meshes. They are converted to scimesh line layers instead (see scimesh::line_layer), which the scimesh rasterizer draws directly, without creating any geometry. This is the cheap way to draw many thin lines, like the edges of a connectome.

Usage

coloredpaths_to_scimesh(cpaths, style = "default")

Arguments

Value

a list of scimesh line layers (class 'scimesh_lines'). One layer per distinct line width, because the width is a property of the layer.

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

Combine two bounding boxes.

Description

Combine two bounding boxes.

Usage

combine_bboxes(bbox1, bbox2)

Arguments

Value

numeric vector of length 6, the box that contains both input boxes.

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

Compute surface contour slice images (internal).

Description

Internal helper that loads a volume and surface meshes, computes the intersection contours of each surface with each slice plane, and draws them onto individual magick slice images. Used by both volvis.lb.with.surface (which grids the results) and volvis.slices.with.surface (which exports them individually).

Usage

compute.surface.contour.slices(
  subjects_dir,
  subject_id,
  volume = "brain",
  surface = "white",
  hemi = "both",
  surface_color = "#FF0000",
  surface_lwd = 1,
  slices = -5,
  axis = 1L,
  scale = 1L,
  silent = TRUE
)

Arguments

Value

named list with entries: images (list of magick images, one per slice), slice_indices (integer vector of 1-based slice indices used), has_contour (logical vector, TRUE if at least one contour segment was drawn on the slice). Also includes metadata entries axis, surfaces, hemis, subject_id for downstream use.

Convert an edge list to a connectivity matrix.

Description

Convert an edge list to a connectivity matrix.

Usage

connectivity.matrix.from.edge.list(edge_list)

Arguments

Value

named list with entries 'matrix' (the connectivity matrix) and 'names' (the node names).

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

Resolve the subjects dir for a context mesh.

Description

Determine the subjects dir from which the requested context mesh can be loaded, if the user did not pass one. For the template subject 'fsaverage' the surfaces are downloaded into the package cache if they are not available, for other subjects the standard search locations are checked, see find.subjectsdir.of.

Usage

context.mesh.resolve.subjects.dir(subject_id = "fsaverage", context = NULL)

Arguments

Value

string, the path to the subjects dir to use, or NULL if the context mesh does not have to be loaded from disk (e.g., because it was passed as a pre-built mesh).

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 gray-scale 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 atlas files for the fs_LR 32k template.

Description

Download a set of cortical atlas files (annotations) defined in the space of the fs_LR 32k template (the HCP-style surface space), based on a declarative manifest file shipped with this package. The atlases (e.g., Schaefer 100-1000, Brainnetome, AAL3) are not part of FreeSurfer and are not subject to the FreeSurfer license. This data is not required for the package to work.

Usage

download_fs_LR_32_atlases(scheme = "https")

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_filepath(). "missing": vector of strings. The names of the files that this function was unable to retrieve.

See Also

Other fs_LR 32k template functions: download_fs_LR_32_labels(), download_fs_LR_32_meshes()

Download label files for the fs_LR 32k template.

Description

Download a set of label files for the fs_LR 32k template (the HCP-style surface space), based on a declarative manifest file shipped with this package. Currently this is the cortex label (?h.cortex.label), which defines the medial wall: all vertices which are not part of the label are medial wall vertices. It can be used to mask the medial wall when projecting volume data to the fs_LR 32k surface, see template.vol2surf (parameter cortex_only). This data is not required for the package to work.

Usage

download_fs_LR_32_labels(scheme = "https")

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_filepath(). "missing": vector of strings. The names of the files that this function was unable to retrieve.

See Also

Other fs_LR 32k template functions: download_fs_LR_32_atlases(), download_fs_LR_32_meshes()

Examples

## Not run: 
   fsbrain::download_fs_LR_32_labels();
   subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
   cortex_lh = subject.label(subjects_dir, "fs_LR_32", "cortex.label", "lh");

## End(Not run)

Download surface meshes for the fs_LR 32k template.

Description

Download a set of surface mesh files for the fs_LR 32k template (the HCP-style surface space), based on a declarative manifest file shipped with this package. The meshes include the white, pial, inflated, very inflated, midthickness, sphere and flat surfaces for both hemispheres. This data is not required for the package to work.

Usage

download_fs_LR_32_meshes(scheme = "https")

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_filepath(). "missing": vector of strings. The names of the files that this function was unable to retrieve.

See Also

Other fs_LR 32k template functions: download_fs_LR_32_atlases(), download_fs_LR_32_labels()

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, scheme = "https")

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.

Usage

download_fsaverage3(accept_freesurfer_license = FALSE, scheme = "https")

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 the FreeSurfer v6 fsaverage6 subject.

Description

Download some relevant files from the FreeSurfer v6 fsaverage6 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.

Usage

download_fsaverage6(accept_freesurfer_license = FALSE, scheme = "https")

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 fsaverage6 is a slightly downsampled (low mesh resolution) version of the standard fsaverage. If you never heard about fsaverage6, you do not need it. You will have to manually re-sample your data in FreeSurfer if you want to use it with fsaverage6.

Download atlas files for the fsaverage template subject.

Description

Download a set of atlas files defined in the space of the fsaverage template subject, based on a declarative manifest file shipped with this package. The atlases (e.g., Schaefer 100-1000, Brainnetome, HCP-MMP1, AAL3) are defined in fsaverage space, but they are not part of FreeSurfer and are not subject to the FreeSurfer license. This data is not required for the package to work. Note that some atlases are not defined on the cortical surface and ship their own surface mesh, e.g., the subcortical atlas of the ENIGMA aseg structures: for those, the 'surf/lh.subcortical' and 'label/lh.subcortical.annot' files (and the same for the right hemisphere) are downloaded, see vis.subcortical.region.values.

Usage

download_fsaverage_atlases(scheme = "https")

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_filepath(). "missing": vector of strings. The names of the files that this function was unable to retrieve.

Download only essential FreeSurfer v6 fsaverage files for quick visualization.

Description

Download a minimal subset of files from the FreeSurfer v6 fsaverage subject, containing only the white surfaces, cortex labels, and curvature files needed for basic 3D visualization (e.g., in a Shiny app). This is much faster than download_fsaverage which downloads 19 files. The files are subject to the FreeSurfer software license, see parameter 'accept_freesurfer_license' for details.

Usage

download_fsaverage_minimal(accept_freesurfer_license = FALSE, scheme = "https")

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

This downloads approximately 8 files instead of the 19 downloaded by download_fsaverage, making it suitable for environments with startup time constraints (e.g., Posit Connect Cloud, shinyapps.io).

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. This function also calls download_fsaverage_atlases, so the atlases defined in fsaverage space (including the subcortical atlas, see vis.subcortical.region.values) become available as well.

Usage

download_optional_data(scheme = "https")

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 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(scheme = "https")

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

Called for side effect of data download.

Download a white matter tract atlas (streamlines).

Description

Download one of the tract atlases that are distributed as streamlines in TrackVis TRK format, one file per white matter bundle. The bundle files (and the provenance and attribution files that document them) are downloaded into the fsbrain file cache, where get_optional_data_filepath can be used to access them. The bundles can then be read with read.tract.bundles and plotted with vis.tracts.

Usage

download_xtract_tracts(
  atlas = "xtract_medium",
  download = TRUE,
  scheme = "https",
  silent = FALSE
)

Arguments

Details

The atlases are the XTRACT atlas of the 42 major white matter tracts (Warrington et al., 2020, doi:10.1126/sciadv.aba8245), whose streamlines were converted from the probabilistic tract atlases and are available in four levels of spatial detail. Note that the bundles are defined in MNI152 space, while the fs_LR_32 and fsaverage templates of fsbrain use a different (fsaverage-like) space: the two spaces are very similar, so the tracts align with the template surfaces well enough for visualization, but they are not identical. If you need an exact alignment, register the template to MNI152 and pass the resulting matrix to the parameter transform_matrix of vis.tracts.

The files are hosted on the rcmd.org server of this project, in the same way as the other optional data of the package, see download_optional_data. They are redistributed from the archives of the MIT licensed 'yabplot' Python package, which uses the same streamlines; the attribution and provenance files that come with them document the origin (see tracts/xtract.attribution.json and the per-level ⁠tracts/xtract_<level>/xtract_<level>.provenance.json⁠ in the file cache). This data is not required for the package to work.

Value

named list. The list has the entries "available" (vector of character strings, the paths of the bundle files that are available in the local file cache) and "missing" (vector of character strings, the files that could not be retrieved).

Note

The levels of detail do not only differ in the number of streamlines, but also in the set of bundles they contain: 'xtract_tiny' has 37 bundles, 'xtract_small' and 'xtract_medium' have 40, and 'xtract_large' has 42 (the bundles 'SLF1_L' and 'Cing_PeriGen_L' are only present in the large one). Since the bundles are selected by name (see the parameter 'bundle_values' of vis.tracts), data that is mapped to bundles has to match the atlas that is actually used.

See Also

Other tracts functions: read.tract.bundles(), vis.tracts()

Examples

## Not run: 
  # Download the small version of the XTRACT atlas:
  download_xtract_tracts("xtract_small");

  # The bundle files are now in the cache:
  atlas_dir = file.path(get_optional_data_filepath("tracts"), "xtract_small");
  list.files(atlas_dir);

## End(Not run)

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).

Draw contour segments onto a magick image.

Description

Draws a set of line segments (as returned by mesh.slice.intersection) onto a magick image. Individual mesh triangles produce small segments, which collectively trace the contour boundary when drawn together.

Usage

draw.segments.on.image(
  img,
  segments,
  slice_axis,
  row_axis,
  col_axis,
  color = "#FF0000",
  lwd = 1,
  coord_scale = 1L
)

Arguments

Value

the modified magick image (invisibly).

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()

Filter a scimesh scene to the meshes visible from a given view

Description

Filter a scimesh scene to the meshes visible from a given view

Usage

filter_scene_by_view(scene, hemi_filter)

Arguments

Value

a flat list of scimesh mesh descriptors for the given view.

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. Note that a subject directory in the package cache is only considered complete if it contains the essential files of a subject, see subject.dir.has.core.files: the cache can contain a subject which only has some atlas files (see download_fsaverage_atlases), and such a directory would make all functions that need the surfaces of the subject fail.

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 the subject directory exists, including locations at which the subject is incomplete (see the description). 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.

Create fs.coloredpaths instance from 2 point matrices.

Description

Create a renderable that draws the line segments from from to to, with one color and (optionally) one width per segment. This is the line equivalent of a coloredmesh, see the details.

Usage

fs.coloredpaths(
  from,
  to,
  col = "#FF0000",
  width = 1,
  depth_test = TRUE,
  lit = FALSE,
  hemi = NULL,
  metadata = list(),
  render = TRUE,
  style = NULL
)

Arguments

Details

Both renderer backends support this class. The rgl backend renders the segments as hardware lines (rgl::segments3d), the headless scimesh backend uses a scimesh line layer (see scimesh::line_layer), which rasterizes the lines directly instead of creating tube geometry. Note that the width of lines is measured in pixels and is a screen-space property, so lines do not get thinner when the camera moves away (this is what hardware line rendering does, and it also means that a line is always visible, even when it is very thin).

The metadata field works exactly like the one of a coloredmesh: if it contains the entries 'src_data' and 'makecmap_options', a colorbar can be plotted for this renderable, see coloredmesh.plot.colorbar.separate.

Value

fs.coloredpaths instance. A named list with entries: "from" (the start points), "to" (the end points), "col" (the colors), "width" (the line widths), "depth_test", "lit", "hemi", "render", and "metadata".

Examples

# A single white line segment from the origin to (10, 0, 0):
p = fs.coloredpaths(matrix(c(0, 0, 0), ncol = 3), matrix(c(10, 0, 0), ncol = 3), col = "#FFFFFF");
p;

# Two segments in different colors, both of them with a width of 2 pixels:
from = matrix(c(0, 0, 0, 0, 0, 10), ncol = 3, byrow = TRUE);
to = matrix(c(10, 0, 0, 0, 10, 10), ncol = 3, byrow = TRUE);
p2 = fs.coloredpaths(from, to, col = c("#FF0000", "#00FF00"), width = 2);

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, fs.coloredpaths, 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.

Map an fsbrain rendering style to scimesh render options

Description

Translates fsbrain style names ("default", "shiny", "semitransparent", "glass", "edges") to scimesh render_options() parameters.

Usage

fsbrain_style_to_scimesh_options(
  style = "default",
  bg_rgba = c(1, 1, 1, 1),
  width = 800L,
  height = 600L
)

Arguments

Value

a scimesh render options list from render_options().

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 current fsbrain renderer backend

Description

Returns the current fsbrain renderer backend setting. When set to "scimesh", fsbrain will use the scimesh software renderer instead of rgl/OpenGL for image export. The default is "rgl". Set it with options(fsbrain.renderer_backend = "scimesh") at the start of your R session.

Usage

get.fsbrain.renderer.backend()

Value

character string, either "rgl" or "scimesh".

Note

Only functions that produce static PNG output are affected. Interactive viewers, animations, and the rglwidget (WebGL) always use rgl.

Examples

## Not run: 
  # Switch to the scimesh software renderer for headless environments
  options(fsbrain.renderer_backend = "scimesh")

  # Check current backend
  get.fsbrain.renderer.backend()

  # Switch back to rgl
  options(fsbrain.renderer_backend = "rgl")

## End(Not run)

Get the anti-aliasing factor for the scimesh backend

Description

Determines the anti-aliasing (supersampling) factor that fsbrain passes to scimesh. The value is taken from the global option 'fsbrain.scimesh.aa_samples'; when that option is unset, an explicitly set scimesh-wide option 'scimesh.aa_samples' is used instead, so that a session-wide scimesh setting is honored. If neither is set, fsbrain uses FSBRAIN_SCIMESH_DEFAULT_AA (2, i.e. 2x2 supersampling).

Usage

get.fsbrain.scimesh.aa.samples()

Details

The order of precedence is: fsbrain.scimesh.aa_samples > scimesh.aa_samples > 2 (the fsbrain default). The option is read for every render call, so it can be changed at any time with options().

Value

single positive integer.

Examples

## Not run: 
  # Higher quality (4x4 supersampling) for all scimesh renders:
  options(fsbrain.scimesh.aa_samples = 4);

  # Back to the fsbrain default (2x2), ignoring a scimesh-wide setting:
  options(fsbrain.scimesh.aa_samples = 2);

  # No anti-aliasing, for fast drafts:
  options(fsbrain.scimesh.aa_samples = 1);

## End(Not run)

Get the output image dimensions for the scimesh backend

Description

Get the output image dimensions for the scimesh backend

Usage

get.fsbrain.scimesh.output.dims()

Value

integer vector of length 2 (width, height), read from the global option 'fsbrain.scimesh.output_dims'. Defaults to 1920x1080.

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.

Note

In addition to the style names listed above, the magic word 'from_mesh' can be passed as parameter 'style' to the rendering functions: it makes them use the style stored in the 'style' field of each individual mesh (see coloredmesh.from.color). This allows you to give individual meshes of a scene their own look, e.g., to render a cortex mesh semi-transparently behind colored data meshes, see vis.subcortical.region.values. Note that the scimesh renderer backend currently only supports the alpha channel of a style, not other material properties.

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. Note that a mesh which carries its own style (in its 'style' field, see coloredmesh.from.color) is rendered with that style whenever the requested style is the 'default' style: this way, scenes that assign individual styles to their meshes look as intended even if the rendering or export function is called without an explicit style.

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()

Compute the first row of every group in a concatenated matrix.

Description

Compute the first row of every group in a concatenated matrix.

Usage

group.start.rows(lengths)

Arguments

Value

integer vector with one entry per group.

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), for camera-based views.

Description

Places the requested highlight points as spheres at their native coordinates. Camera-based views keep the meshes unrotated and apply the view rotation via the camera, so highlight points must NOT be rotated (this matches the scimesh backend). See dev_tools/TODO_FSBRAIN_RGL_CAM.md.

Usage

handle.rglactions.highlight.points(rglactions, 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(), hemilist.from.prefixed.list(), hemilist.get.combined.data(), hemilist.unwrap(), hemilist.wrap(), 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(), hemilist.derive.hemi(), hemilist.get.combined.data(), hemilist.unwrap(), hemilist.wrap(), 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(), hemilist.derive.hemi(), hemilist.from.prefixed.list(), hemilist.unwrap(), hemilist.wrap(), 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(), hemilist.derive.hemi(), hemilist.from.prefixed.list(), hemilist.get.combined.data(), hemilist.wrap(), 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(), hemilist.derive.hemi(), hemilist.from.prefixed.list(), hemilist.get.combined.data(), hemilist.unwrap(), 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

Convert a vector of hex colors to an Nx4 RGBA float matrix

Description

Convert a vector of hex colors to an Nx4 RGBA float matrix

Usage

hex_colors_to_rgba_matrix(hex_colors)

Arguments

Value

Nx4 numeric matrix of RGBA values in the range 0..1.

Convert hex color string to RGBA float vector

Description

Converts a hex color string like "#FF0000" or "#FF0000FF" to a length-4 RGBA numeric vector with values in the range 0..1.

Usage

hex_to_rgba(hex)

Arguments

Value

numeric vector of length 4, RGBA values in 0..1 range.

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.rglwidget(), vis.subcortical.region.values(), vis.subject.annot(), vis.subject.label(), vis.subject.morph.native(), vis.subject.morph.standard(), vis.subject.pre(), vis.symmetric.data.on.subject(), vis.volume.clusters(), vis.volume.on.surface(), 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.rglwidget(), vis.subcortical.region.values(), vis.subject.annot(), vis.subject.label(), vis.subject.morph.native(), vis.subject.morph.standard(), vis.subject.pre(), vis.symmetric.data.on.subject(), vis.volume.clusters(), vis.volume.on.surface(), 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)

Convert highlight points (rglactions) to scimesh sphere meshes

Description

Convert highlight points (rglactions) to scimesh sphere meshes

Usage

highlight_points_to_scimesh(rglactions, hemi_filter = "both")

Arguments