Package 'ggseg'

Add view labels to brain atlas plots

Description

Annotates each brain view with a text label positioned above the view's bounding box. For cortical atlases, labels show hemisphere and view (e.g., "left lateral"). For subcortical and tract atlases, labels show the view name directly (e.g., "axial_1", "sagittal").

Usage

annotate_brain(
  atlas,
  position = position_brain(),
  hemi = NULL,
  view = NULL,
  size = 3,
  colour = "grey30",
  family = "mono",
  nudge_y = 0,
  ...
)

Arguments

atlas	A 'brain_atlas' object (e.g. 'dk()', 'aseg()').
position	A [position_brain()] object or position specification matching the one used in [geom_brain()].
hemi	Character vector of hemispheres to include. If 'NULL' (default), all hemispheres are included.
view	Character vector of views to include. If 'NULL' (default), all views are included.
size	Text size in mm (default: '3').
colour	Text colour (default: '"grey30"').
family	Font family (default: '"mono"').
nudge_y	Additional vertical offset for labels (default: '0').
...	Additional arguments passed to [ggplot2::annotate()].

Details

Labels respect the repositioning done by [position_brain()], so the same 'position' argument should be passed to both [geom_brain()] and 'annotate_brain()'.

Value

A ggplot2 annotation layer.

Examples

library(ggplot2)

pos <- position_brain(hemi ~ view)
ggplot() +
  geom_brain(atlas = dk(), position = pos, show.legend = FALSE) +
  annotate_brain(atlas = dk(), position = pos)

ggplot() +
  geom_brain(atlas = dk(), show.legend = FALSE) +
  annotate_brain(atlas = dk())

---

Join user data with a brain atlas

Description

Performs a full join between user data and a brain atlas. Grouped data is handled automatically, producing one complete atlas per group.

Usage

brain_join(data, atlas, by = NULL)

Arguments

data	A data.frame with a column matching an atlas column (typically '"region"'). Can be grouped with [dplyr::group_by()].
atlas	A 'ggseg_atlas' object or data.frame containing atlas data.
by	Character vector of column names to join by. If 'NULL' (default), columns are detected automatically.

Value

An 'sf' object if the atlas contains geometry, otherwise a tibble.

Examples

someData <- data.frame(
  region = c(
    "transverse temporal", "insula",
    "precentral", "superior parietal"
  ),
  p = sample(seq(0, .5, .001), 4),
  stringsAsFactors = FALSE
)

brain_join(someData, dk())
brain_join(someData, dk(), "region")

---

Plot brain atlas regions

Description

A ggplot2 geom for rendering brain atlas regions as filled polygons, built on top of [ggplot2::geom_sf()]. Accepts a 'brain_atlas' object and automatically joins user data to atlas geometry for visualisation.

Usage

geom_brain(
  mapping = aes(),
  data = NULL,
  atlas,
  hemi = NULL,
  view = NULL,
  position = position_brain(),
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

mapping	Set of aesthetic mappings created by [ggplot2::aes()].
data	A data.frame containing variables to map. If 'NULL', the atlas is plotted without user data.
atlas	A 'ggseg_atlas' object (e.g. 'dk()', 'aseg()', 'tracula()').
hemi	Character vector of hemispheres to include (e.g. '"left"', '"right"'). Defaults to all hemispheres in the atlas.
view	Character vector of views to include, as recorded in the atlas data. For cortical atlases: '"lateral"', '"medial"'. For subcortical/tract atlases: slice identifiers like '"axial_3"'. Defaults to all views.
position	Position adjustment, either as a string or the result of a call to [position_brain()].
show.legend	Logical. Should this layer be included in the legends?
inherit.aes	Logical. If 'FALSE', overrides the default aesthetics rather than combining with them.
...	Additional arguments passed to [ggplot2::geom_sf()].

Value

A list of ggplot2 layer and coord objects.

GeomBrain ggproto

'GeomBrain' is a [ggplot2::Geom] ggproto object that handles rendering of brain atlas polygons. It is used internally by [geom_brain()] and should not typically be called directly.

Examples

library(ggplot2)

ggplot() +
  geom_brain(atlas = dk())

---

Alter brain atlas position

Description

Function to be used in the position argument in geom_brain to alter the position of the brain slice/views.

Usage

position_brain(position = "horizontal", nrow = NULL, ncol = NULL, views = NULL)

Arguments

position	Formula describing the rows ~ columns organisation for cortical atlases (e.g., 'hemi ~ view'). For subcortical/tract atlases, can be "horizontal", "vertical", or a formula with 'type ~ .' where type is extracted from view names like "axial_1" -> "axial".
nrow	Number of rows for grid layout. If NULL (default), calculated automatically. Only used for subcortical/tract atlases when position is not a formula.
ncol	Number of columns for grid layout. If NULL (default), calculated automatically. Only used for subcortical/tract atlases when position is not a formula.
views	Character vector specifying which views to include and their order. If NULL (default), all views are included in their original order. Only applies to subcortical/tract atlases.

Value

a ggproto object

Examples

library(ggplot2)

# Cortical atlas with formula
ggplot() +
  geom_brain(
    atlas = dk(), aes(fill = region),
    position = position_brain(. ~ view + hemi),
    show.legend = FALSE
  )

ggplot() +
  geom_brain(
    atlas = dk(), aes(fill = region),
    position = position_brain(view ~ hemi),
    show.legend = FALSE
  )


ggplot() +
  geom_brain(
    atlas = aseg(), aes(fill = region),
    position = position_brain(nrow = 2)
  )

ggplot() +
  geom_brain(
    atlas = aseg(), aes(fill = region),
    position = position_brain(
      views = c("sagittal", "axial_3", "coronal_2"),
      nrow = 1
    )
  )

ggplot() +
  geom_brain(
    atlas = aseg(), aes(fill = region),
    position = position_brain(type ~ .)
  )

---

Reposition brain slices

Description

Function for repositioning pre-joined atlas data (i.e. data and atlas already joined to a single data frame). This makes it possible for users to reposition the geometry data for the atlas for control over final plot layout. For even more detailed control over the positioning, the "hemi" and "view" columns should be converted into factors and ordered by wanted order of appearance.

Usage

reposition_brain(
  data,
  position = "horizontal",
  nrow = NULL,
  ncol = NULL,
  views = NULL
)

Arguments

data	sf-data.frame of joined brain atlas and data
position	Position formula for slices. For cortical atlases, use formulas like 'hemi ~ view'. For subcortical/tract atlases, use "horizontal", "vertical", or 'type ~ .' for type-based layout.
nrow	Number of rows for grid layout (subcortical/tract only)
ncol	Number of columns for grid layout (subcortical/tract only)
views	Character vector specifying view order (subcortical/tract only)

Value

sf-data.frame with re-positioned slices

Examples

reposition_brain(dk(), hemi ~ view)
reposition_brain(dk(), view ~ hemi)
reposition_brain(dk(), hemi + view ~ .)
reposition_brain(dk(), . ~ hemi + view)


reposition_brain(aseg(), nrow = 2)
reposition_brain(aseg(), views = c("sagittal", "axial_3"))

---

Colour and fill scales from brain atlas palettes

Description

'r lifecycle::badge("deprecated")'

Atlas palettes are now applied automatically by [geom_brain()]. Use [scale_fill_brain_manual()] for custom palettes.

Usage

scale_brain(
  name = "dk",
  na.value = "grey",
  ...,
  aesthetics = c("fill", "colour", "color")
)

scale_colour_brain(name = "dk", na.value = "grey", ...)

scale_color_brain(name = "dk", na.value = "grey", ...)

scale_fill_brain(name = "dk", na.value = "grey", ...)

Arguments

name	String name of the atlas palette (e.g. '"dk"', '"aseg"').
na.value	Colour for 'NA' entries (default: '"grey"').
...	Additional arguments passed to [ggseg.formats::atlas_palette()].
aesthetics	Which aesthetic to scale: '"fill"', '"colour"', or '"color"'.

Value

A ggplot2 scale object.

Examples

## Not run: 
library(ggplot2)
ggplot() +
  geom_brain(atlas = dk(), aes(fill = region), show.legend = FALSE) +
  scale_brain("dk")

## End(Not run)

---

Manual colour and fill scales for brain plots

Description

Apply a custom named colour palette to brain atlas plots. Use this when you want to override the atlas default colours with your own colour mapping.

Usage

scale_brain_manual(
  palette,
  na.value = "grey",
  ...,
  aesthetics = c("fill", "colour", "color")
)

scale_colour_brain_manual(...)

scale_color_brain_manual(...)

scale_fill_brain_manual(...)

Arguments

palette	Named character vector mapping region names to colours.
na.value	Colour for 'NA' entries (default: '"grey"').
...	Additional arguments (unused).
aesthetics	Which aesthetic to scale: '"fill"', '"colour"', or '"color"'.

Value

A ggplot2 scale object.

Examples

library(ggplot2)

pal <- c("insula" = "red", "precentral" = "blue")
ggplot() +
  geom_brain(atlas = dk(), aes(fill = region), show.legend = FALSE) +
  scale_fill_brain_manual(palette = pal)

---

Deprecated scale functions

Description

'r lifecycle::badge("deprecated")'

These functions have been renamed for clarity: - 'scale_brain2()' -> [scale_brain_manual()] - 'scale_fill_brain2()' -> [scale_fill_brain_manual()] - 'scale_colour_brain2()' -> [scale_colour_brain_manual()] - 'scale_color_brain2()' -> [scale_color_brain_manual()]

Usage

scale_brain2(...)

scale_colour_brain2(...)

scale_color_brain2(...)

scale_fill_brain2(...)

Arguments

...	Arguments passed to the replacement function.

Value

A ggplot2 scale object.

Examples

pal <- c("transverse temporal" = "#FF0000", "insula" = "#00FF00")
suppressWarnings(scale_fill_brain_manual(palette = pal))

---

Axis and label scales for brain atlas plots

Description

Add axis labels and tick labels corresponding to brain atlas regions. These scales add hemisphere or view labels to the x and y axes based on the atlas layout.

Usage

scale_continous_brain(
  atlas = dk(),
  position = "dispersed",
  aesthetics = c("y", "x")
)

scale_x_brain(...)

scale_y_brain(...)

scale_labs_brain(atlas = dk(), position = "dispersed", aesthetics = "labs")

Arguments

atlas	A 'ggseg_atlas' object or data.frame containing atlas data.
position	Layout style: '"dispersed"' (default) or '"stacked"'.
aesthetics	Which axis to scale: '"x"', '"y"', or '"labs"'.
...	Additional arguments passed to [adapt_scales()].

Value

A ggplot2 scale or labs object.

Examples

library(ggplot2)

ggplot() +
  geom_brain(atlas = dk()) +
  scale_x_brain() +
  scale_y_brain() +
  scale_labs_brain()

---

Themes for brain atlas plots

Description

A set of ggplot2 themes designed for brain atlas visualisations. All themes remove axis ticks and grid lines for a clean presentation.

Usage

theme_brain(text.size = 12, text.family = "mono")

theme_darkbrain(text.size = 12, text.family = "mono")

theme_custombrain(
  plot.background = "white",
  text.colour = "darkgrey",
  text.size = 12,
  text.family = "mono"
)

theme_brain2(
  plot.background = "white",
  text.colour = "darkgrey",
  text.size = 12,
  text.family = "mono"
)

Arguments

text.size	Text size in points (default: '12').
text.family	Font family (default: '"mono"').
plot.background	Background fill colour ('theme_custombrain' and 'theme_brain2' only).
text.colour	Text colour ('theme_custombrain' and 'theme_brain2' only).

Details

'theme_brain'

Default theme. Transparent background, no axes, no grid.

'theme_darkbrain'

Dark theme with black background and light text.

'theme_custombrain'

Fully customisable background, text colour, size, and font.

'theme_brain2'

Like 'theme_custombrain' but with axis text removed entirely.

Value

A [ggplot2::theme] object.

See Also

[geom_brain()], [ggplot2::theme()]

Examples

library(ggplot2)

p <- ggplot() +
  geom_brain(atlas = dk())

p +
  theme_brain()

p +
  theme_darkbrain()

---