Package 'fsbrain'

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

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.

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.

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

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

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)

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.

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

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

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

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

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.

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.

Description

Return the standard fsbrain heat colormap.

Usage

cm.heat(report = FALSE)

Arguments

Note

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

Description

Return the standard fsbrain qualitative colormap.

Usage

cm.qual(report = FALSE)

Arguments

Note

Returns some qualitative palette, suitable for visualizing categorical data.

Description

Return the standard fsbrain sequential colormap.

Usage

cm.seq(report = FALSE)

Arguments

Note

This returns a sequential, multi-hue palette.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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

Description

Return diverging color list

Usage

colorlist.brain.clusters(num_colors)

Arguments

Value

vector of 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"))));

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

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

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

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

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

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

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.

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

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)

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

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

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)

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

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.

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.

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

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.

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.

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.

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.

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)

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)

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)

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

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

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

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.

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

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.

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.

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)

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.

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.

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.

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.

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

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.

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)

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)

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)

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.

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)

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.

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)

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)

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

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.

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

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)

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)

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)

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)

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)

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)

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

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)

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

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

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)

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)

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.

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)

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