Package {ggseg}

Title:	Plotting Tool for Brain Atlases
Version:	2.2.0
Description:	Provides a 'ggplot2' geom and position for visualizing brain region data on cortical, subcortical, and white matter tract atlases. Brain atlas geometries are stored as polygon data, enabling seamless integration with the 'ggplot2' ecosystem including faceting, custom scales, and themes. Mowinckel & Vidal-Piñeiro (2020) <doi:10.1177/2515245920928009>.
License:	MIT + file LICENSE
URL:	https://ggsegverse.github.io/ggseg/, https://github.com/ggsegverse/ggseg
BugReports:	https://github.com/ggsegverse/ggseg/issues
Depends:	R (≥ 3.3)
Imports:	cli, dplyr (≥ 1.0.0), ggplot2 (≥ 3.3), ggseg.formats (≥ 0.0.3), grid, lifecycle, rlang, tidyr (≥ 1.0.0), utils
Suggests:	covr, devtools, here, knitr, rmarkdown, sf, spelling, testthat (≥ 3.0.0), vdiffr, withr
VignetteBuilder:	knitr
Config/Needs/website:	ggsegverse/ggseg.docs
Config/testthat/edition:	3
Config/testthat/parallel:	true
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.3
NeedsCompilation:	no
Packaged:	2026-06-21 17:59:50 UTC; athanasm
Author:	Athanasia Mo Mowinckel [aut, cre], Didac Vidal-Piñeiro [aut], Ramiro Magno [ctb], Center for Lifespan Changes in Brain and Cognition, University of Oslo, Norway [cph]
Maintainer:	Athanasia Mo Mowinckel <a.m.mowinckel@psykologi.uio.no>
Repository:	CRAN
Date/Publication:	2026-06-22 05:20:16 UTC

ggseg: Visualise brain atlas data with ggplot2

Description

Provides a ggplot2 geom and position for visualising brain region data on cortical, subcortical, and white matter tract atlases. Brain atlas geometries are stored as simple features (sf), enabling seamless integration with the ggplot2 ecosystem including faceting, custom scales, and themes.

'ggseg()' is defunct as of version 2.0.0. Use 'ggplot() + geom_brain()' instead.

Usage

ggseg(...)

Arguments

Details

The main entry point is [geom_brain()], which accepts a 'ggseg_atlas' object and optional user data. Use [position_brain()] to control the layout of brain slices/views.

Value

Does not return; always raises an error.

Author(s)

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

Authors:

• Didac Vidal-Piñeiro d.v.pineiro@psykologi.uio.no (ORCID)

Other contributors:

• Ramiro Magno ramiro.magno@gmail.com (ORCID) [contributor]

• Center for Lifespan Changes in Brain and Cognition, University of Oslo, Norway [copyright holder]

See Also

Useful links:

• https://ggsegverse.github.io/ggseg/

• https://github.com/ggsegverse/ggseg

• Report bugs at https://github.com/ggsegverse/ggseg/issues

[geom_brain()] for the replacement API.

Examples

## Not run: 
ggseg()

## End(Not run)

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",
  padding = 0.05,
  nudge_y = 0,
  ...
)

Arguments

Details

Pass the same 'position' you gave [geom_brain()] and the labels line up with the views automatically.

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

Matches your data to a brain atlas by a shared column (usually 'region'), keeping every atlas region whether or not you have a value for it. Grouped data (via [dplyr::group_by()]) gives one complete atlas per group. You rarely need this directly – [geom_brain()] joins your data for you; reach for 'brain_join()' when you want the joined sf object yourself.

Usage

brain_join(data, atlas, by = NULL)

Arguments

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

Keep brain shapes undistorted

Description

Fixes the aspect ratio so brains aren't stretched by the shape of the plotting window. [geom_brain()] adds 'coord_brain()' for you, so you rarely need to call it yourself – reach for it only to adjust the 'ratio' or 'clip' behaviour. You can safely add your own coord or stack several 'geom_brain()' layers; it steps aside cleanly.

Usage

coord_brain(ratio = 1, clip = "off", ...)

Arguments

Value

A ggplot2 coordinate system that registers as a default.

Examples

library(ggplot2)
## Not run: 
poly <- ggseg.formats::as_polygon_atlas(dk())
# Equivalent to the default; shown explicitly:
ggplot() +
  geom_brain(atlas = poly) +
  coord_brain()

## End(Not run)

Plot brain atlas regions

Description

Colour brain regions by your own values. Give 'geom_brain()' an atlas like 'dk()' and a data frame, and it matches your values to the right regions and lays out the brain views for you. No data? It just draws the atlas.

Usage

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

Arguments

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

Deprecated sf brain geom

Description

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

The sf rendering path is deprecated. 'geom_brain_sf()' renders an atlas via [ggplot2::geom_sf()] and [coord_sf()][ggplot2::coord_sf]. For new code, use [geom_brain()] (the polygon default), or convert the atlas with 'as_sf_atlas()' and use [ggplot2::geom_sf()] directly for the full sf toolkit (labels, other sf layers).

Usage

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

Arguments

Value

A list of ggplot2 layer and coord objects.

Arrange brain atlas views

Description

Controls how an atlas's hemispheres and views are arranged in the plot – side by side, stacked, or in a grid – and can zoom each view in on the regions you care about. Pass the result to the 'position' argument of [geom_brain()] (or [annotate_brain()]).

Usage

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

Arguments

Value

A layout specification to hand to [geom_brain()]'s 'position' argument.

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

Deprecated sf brain-view layout

Description

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

The sf rendering path is deprecated. 'position_brain_sf()' returns the legacy 'PositionBrain' ggproto for use with [geom_brain_sf()]. For new code, use [position_brain()] (the polygon default), or convert the atlas with 'as_sf_atlas()' and use [ggplot2::geom_sf()] directly.

Usage

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

Arguments

Value

A 'PositionBrain' ggproto object.

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

ggseg.formats

aseg, dk, suit, tracula

Reposition brain slices

Description

Repositions pre-joined sf atlas data (i.e. data and atlas already joined to a single sf data frame) for control over final plot layout. For even more detailed control, convert the "hemi" and "view" columns into factors ordered by wanted order of appearance.

Usage

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

Arguments

Details

This is the sf layout helper. It requires the 'sf' package (an optional dependency); for the sf-free default, build a layout with [position_brain()] and pass it to [geom_brain()].

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

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)

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

Value

A ggplot2 scale object.

Examples

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

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

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)

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

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

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