Title: Tri-Surface Mesh Plots for Brain Atlases
Version: 1.6.3
Description: Mainly contains a plotting function ggseg3d(), and data of two standard brain atlases (Desikan-Killiany and aseg). By far, the largest bit of the package is the data for each of the atlases. The functions and data enable users to plot tri-surface mesh plots of brain atlases, and customise these by projecting colours onto the brain segments based on values in their own data sets. Functions are wrappers for 'plotly'. Mowinckel & Vidal-Piñeiro (2020) <doi:10.1177/2515245920928009>.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.1.1
Depends: R (≥ 2.10)
LazyData: true
LazyDataCompression: xz
Imports: dplyr, plotly, magrittr, scales, tidyr, utils,
Suggests: knitr, rmarkdown, covr, testthat (≥ 2.1.0), devtools, processx, spelling
URL: https://github.com/ggseg/ggseg3d/
BugReports: https://github.com/ggseg/ggseg3d/issues/
Language: en-US
NeedsCompilation: no
Packaged: 2021-05-31 11:46:23 UTC; athanasm
Author: Athanasia Mo Mowinckel ORCID iD [aut, cre], Didac Vidal-Piñeiro ORCID iD [aut]
Maintainer: Athanasia Mo Mowinckel <a.m.mowinckel@psykologi.uio.no>
Repository: CRAN
Date/Publication: 2021-06-01 07:20:02 UTC

ggseg3d: Plot brain segmentations with plotly

Description

Plotting results from analyses done on data derived from brain segmentations is a common need, but may be quite laborious. Results from such analyses are usually easier to interpret if the plot can mimmick the shape and position in the brain it represents.

ggseg3d plots and returns a plotly mesh3d object.

Usage

ggseg3d(
  .data = NULL,
  atlas = "dk_3d",
  surface = "LCBC",
  hemisphere = c("right", "subcort"),
  label = "region",
  text = NULL,
  colour = "colour",
  palette = NULL,
  na.colour = "darkgrey",
  na.alpha = 1,
  show.legend = TRUE,
  options.legend = NULL,
  ...
)

Arguments

.data

A data.frame to use for plot aesthetics. Must include a column called "region" corresponding to regions.

atlas

Either a string with the name of a 3d atlas to use.

surface

String. Which surface to plot. Either "pial","white", or "inflated"[default]

hemisphere

String. Hemisphere to plot. Either "left" or "right"[default], can also be "subcort".

label

String. Quoted name of column in atlas/data that should be used to name traces

text

String. Quoted name of column in atlas/data that should be added as extra information in the hover text.

colour

String. Quoted name of column from which colour should be supplied

palette

String. Vector of colour names or HEX colours. Can also be a named numeric vector, with colours as names, and breakpoint for that colour as the value

na.colour

String. Either name, hex of RGB for colour of NA in colour.

na.alpha

Numeric. A number between 0 and 1 to control transparency of NA-regions.

show.legend

Logical. Toggle legend if colour is numeric.

options.legend

list of layout changes to colour bar

...

additional arguments to add_trace

Available surfaces:

  • 'inflated:' Fully inflated surface

  • 'semi-inflated:' Semi-inflated surface

  • 'white:' white matter surface

Details

This package contains data from various brain parcellations, with convenient functions to inspect the results directly on a brain-plot wither with plotly in 3d meshes.

Value

a plotly tri-surface mesh plot

Author(s)

Maintainer: Athanasia Mo Mowinckel a.m.mowinckel@psykologi.uio.no (ORCID)

Authors:

Athanasia Mowinckel and Didac Piñeiro

See Also

Useful links:

plot_ly, add_trace, layout, the plotly package

Examples

ggseg3d()
ggseg3d(hemisphere = "left")
ggseg3d(surface = "inflated")
ggseg3d(show.legend = FALSE)

Add glass brain to ggseg3d plot

Description

Adds a translucent brain on top of a ggseg3d plot to create a point of reference, particularly important for sub-cortical plots.

Usage

add_glassbrain(
  p,
  hemisphere = c("left", "right"),
  colour = "#cecece",
  opacity = 0.3
)

Arguments

p

plotly object

hemisphere

string. hemisphere to plot ("left" or "right")

colour

string. colour to give the glass brain

opacity

numeric. transparency of the glass brain (0-1 float)

Value

plotly object with glass brain tri-surface mesh

Examples

library(dplyr)
ggseg3d(atlas="aseg_3d") %>%
   add_glassbrain("left")

FreeSurfer automatic subcortical segmentation of a brain volume

Description

Coordinate data for the subcortical parcellations implemented in FreeSurfer.

Usage

data(aseg_3d)

Format

A tibble with 4 observations and a nested data.frame

surf

type of surface ('inflated' or 'white')

hemi

hemisphere ('left“ or 'right')

data

data.frame of necessary variables for plotting

atlas

String. atlas name

roi

numbered region from surface

annot

concatenated region name

label

label 'hemi_annot' of the region

mesh

list of meshes in two lists: vb and it

region

name of region in full

colour

HEX colour of region

References

Fischl et al., (2002). Neuron, 33:341-355 (PubMed)

See Also

Other ggseg3d_atlases: dk_3d

Examples

data(aseg_3d)

Desikan-Killiany Cortical Atlas

Description

Mesh data for the Desikan-Killiany Cortical atlas, with 40 regions in on the cortical surface of the brain.

Usage

data(dk_3d)

Format

A tibble with 4 observations and a nested data.frame

surf

type of surface ('inflated' or 'white')

hemi

hemisphere ('left“ or 'right')

data

data.frame of necessary variables for plotting

atlas

String. atlas name

roi

numbered region from surface

annot

concatenated region name

label

label 'hemi_annot' of the region

mesh

list of meshes in two lists: vb and it

acronym

abbreviated name of annot

lobe

lobe localization

region

name of region in full

colour

HEX colour of region

Details

A nested tibble for all available surfaces and hemispheres

References

Fischl et al. (2004) Cerebral Cortex 14:11-22 (PubMed)

See Also

Other ggseg3d_atlases: aseg_3d

Examples

data(dk_3d)

'ggseg3d_atlas' class

Description

The 'ggseg_3datlas' class is a subclass of ['data.frame'][base::data.frame()], created in order to have different default behaviour. It heavily relies on the "tibble" ['tbl_df'][tibble::tibble()]. [tidyverse](https://www.tidyverse.org/packages/), including [dplyr](http://dplyr.tidyverse.org/), [ggplot2](http://ggplot2.tidyverse.org/), [tidyr](http://tidyr.tidyverse.org/), and [readr](http://readr.tidyverse.org/).

Usage

as_ggseg3d_atlas(x, return = FALSE)

Arguments

x

data.frame to be made a ggseg-atlas

return

return logical

Value

an object of class 'ggseg3d_atlas'. A nested tibble of different brain surface shapes, hemispheres and tri-surface mesh information for different brain regions in a specific atlas.

Properties of 'ggseg3d_atlas'

Objects of class 'ggseg3d_atlas' have: * A 'class' attribute of 'c("ggseg3d_atlas", "tbl_df", "tbl", "data.frame")'. * A base type of '"list"', where each element of the list has the same [NROW()]. * A lot of this script and its functions are taken from the ['tibble'][tibble::tibble()]-package

See Also

[tibble()], [as_tibble()], [tribble()], [print.tbl()], [glimpse()]

Examples

tmp <- as.data.frame(dk_3d)
class(tmp)
new_atlas <- as_ggseg3d_atlas(tmp)
class(new_atlas)

Check if is ggseg_atlas-class

Description

Check if is ggseg_atlas-class

Usage

is_ggseg3d_atlas(x)

Arguments

x

atlas object to check

Value

logical

Pan camera position of ggseg3d plot

Description

The default position for plotly mesh plots are not satisfying for brain plots. This convenience function can pan the camera to lateral or medial view, or to custom made views if you are plotly savvy.

Usage

pan_camera(p, camera, aspectratio = 1)

Arguments

p

plotly object

camera

string or list.

aspectratio

camera aspect ratio

Value

plotly object

Examples

library(dplyr)
ggseg3d() %>%
   pan_camera("right lateral")

Remove axis information from ggseg3d plot

Description

When publishing data visualisation in 3d mesh plots in general the axes are not important, at least they are not for ggseg3d, where the axis values are arbitrary.

Usage

remove_axes(p)

Arguments

p

plotly object

Value

plotly object without axes

Examples

library(magrittr)
ggseg3d() %>%
   remove_axes()