geom_brain {ggbrain}

Adds a raster layer to the ggbrain plot, displaying pixels from the specified layer definition

Description

Adds a raster layer to the ggbrain plot, displaying pixels from the specified layer definition

Usage

geom_brain(
  definition = NULL,
  name = NULL,
  fill = NULL,
  fill_scale = NULL,
  mapping = NULL,
  limits = NULL,
  breaks = NULL,
  show_legend = TRUE,
  interpolate = FALSE,
  unify_scales = TRUE,
  alpha = NULL,
  blur_edge = NULL,
  fill_holes = NULL,
  remove_specks = NULL,
  trim_threads = NULL
)

Arguments

definition

a character string of the contrast or image definition used to define this layer. Can be a simple image name (e.g., 'underlay') or a contrast string (e.g., 'overlay[overlay > 5]')

name

the name of this layer, used for referencing in layer and panel modifications

fill

A character string indicating the color used to fill all non-NA pixels in this layer. This is used to set the fill color, in distinction to color mapping: mapping=aes(fill=<variable>).

fill_scale

a ggplot scale_fill_* object used for mapping the fill column to the color of pixels in this layer.

mapping

the aesthetic mapping of the layer data to the display. Should be an aes() object and supports fill (color of filled pixels). Default is aes(fill=value), which maps the numeric value of the layer data to the fill color of the squares at each spatial position. For labeled data, you might use aes(fill=<label_col_name>).

limits

if provided, sets the upper and lower bounds on the scale

breaks

if provided, a function to draw the breaks on the fill scale

show_legend

if TRUE, show the fill scale in the plot legend

interpolate

passes to geom_raster and controls whether the fill is interpolated over continuous space

unify_scales

if TRUE, when this layer is reused across panels, unify the scales to match

alpha

a number between 0 and 1 that sets the alpha transparency of this layer. Default: 1

blur_edge

the standard deviation (sigma) of a Gaussian kernel applied to the edge of this layer to smooth it. This makes the layer less jagged in appearance and is akin to antialiasing.

fill_holes

An optional positive integer specifying the size of holes (in pixels) inside clusters to be filled by nearest neighbor imputation. Default: 0.

remove_specks

An optional positive integer specifying the size of specks (in pixels) to be removed from each slice prior to display. Specks are small clusters that may be distracting and contribute to a 'salt and pepper' appearance.

trim_threads

the minimum number of neighboring pixels (including diagonals) that must be present to keep a pixel.

Details

Note that the fill_scale and limits must be specified at the time of the geom_brain creation in order for them to be mapped properly within ggplot. Because we overlay many raster layers in a ggplot object that all use the fill aesthetic mapping, it becomes hard to map the color scales after the layer is created using the typical + scale_fill_* syntax, and similarly for scale limits.

Value

a ggb object populated with the relevant geom_brainand the action of 'add_layers'

Examples

  # T1-weighted template
  t1 <- system.file("extdata", "mni_template_2009c_3mm.nii.gz", package = "ggbrain")

  # signed reward prediction error map
  signed_pe <- system.file("extdata", "pe_ptfce_fwep_0.05.nii.gz", package = "ggbrain")
  
  gg_obj <- ggbrain() +
    images(c(underlay = t1, overlay = signed_pe)) +
    slices(c("x = 25%", "x = 75%")) +
    geom_brain("underlay") +
    geom_brain(definition="overlay[overlay > 1]", fill_scale=ggplot2::scale_fill_viridis_c("pos z"))