Title: Plotting Tool for Brain Atlases
Version: 2.0.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 simple features ('sf'), 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, grid, lifecycle, sf, stats, tidyr (≥ 1.0.0), utils
Suggests: covr, devtools, here, knitr, rmarkdown, spelling, testthat (≥ 3.0.0), vdiffr
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
SystemRequirements: C++17, GDAL (>= 2.0.1), GEOS (>= 3.4.0), PROJ (>= 4.8.0)
NeedsCompilation: no
Packaged: 2026-02-18 21:25:47 UTC; athanasm
Author: Athanasia Mo Mowinckel ORCID iD [aut, cre], Didac Vidal-Piñeiro ORCID iD [aut], Ramiro Magno ORCID iD [aut]
Maintainer: Athanasia Mo Mowinckel <a.m.mowinckel@psykologi.uio.no>
Repository: CRAN
Date/Publication: 2026-02-19 16:10:02 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

...

Ignored.

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:

See Also

Useful links:

[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",
  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 ~ .)
  )

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, tracula

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)

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.

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)

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