Arranging brain views

In ggseg: Plotting Tool for Brain Atlases

#| label: setup
#| include: false
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)

#| label: load-packages
library(ggseg)
library(ggplot2)

A brain atlas typically has several views -- lateral and medial for cortical atlases, or axial, coronal, and sagittal slices for subcortical and tract atlases. position_brain() controls how those views are arranged in the final plot.

The function works differently depending on the atlas type, so this vignette covers cortical and subcortical/tract atlases separately.

Cortical atlases

Cortical atlases like dk have two layout dimensions: hemi (left or right) and view (lateral, medial, etc.). The formula syntax mirrors facet_grid() -- left side is rows, right side is columns:

#| label: fig-hemi-by-view
#| fig-cap: "Cortical atlas with hemispheres as rows and views as columns."
ggplot() +
  geom_brain(
    atlas = dk(),
    position = position_brain(hemi ~ view),
    show.legend = FALSE
  ) +
  theme_void()

Flip the formula to transpose the layout:

#| label: fig-view-by-hemi
#| fig-cap: "Transposed layout with views as rows and hemispheres as columns."
ggplot() +
  geom_brain(
    atlas = dk(),
    position = position_brain(view ~ hemi),
    show.legend = FALSE
  ) +
  theme_void()

Stacking all views

Use . with + to collapse everything into a single row or column. This is handy for compact figures:

#| label: fig-single-row
#| fig-cap: "All brain views stacked in a single row."
ggplot() +
  geom_brain(
    atlas = dk(),
    position = position_brain(. ~ hemi + view),
    show.legend = FALSE
  ) +
  theme_void()

#| label: fig-single-column
#| fig-cap: "All brain views stacked in a single column."
ggplot() +
  geom_brain(
    atlas = dk(),
    position = position_brain(hemi + view ~ .),
    show.legend = FALSE
  ) +
  theme_void()

Subcortical and tract atlases

Subcortical atlases like aseg and tract atlases like tracula don't have the hemisphere/view pairing that cortical atlases do. Their views are individual slices (e.g. "axial_3", "sagittal"). That opens up a different set of positioning tools.

Horizontal and vertical

The simplest options. "horizontal" is the default:

#| label: fig-aseg-horizontal
#| fig-cap: "Subcortical atlas views arranged horizontally."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain("horizontal"),
    show.legend = FALSE
  ) +
  theme_void()

#| label: fig-aseg-vertical
#| fig-cap: "Subcortical atlas views arranged vertically."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain("vertical"),
    show.legend = FALSE
  ) +
  theme_void()

Grid layouts

When you have many views, a grid keeps things readable. Specify nrow, ncol, or both:

#| label: fig-aseg-nrow
#| fig-cap: "Subcortical atlas views in a two-row grid."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain(nrow = 2),
    show.legend = FALSE
  ) +
  theme_void()

#| label: fig-aseg-ncol
#| fig-cap: "Subcortical atlas views in a three-column grid."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain(ncol = 3),
    show.legend = FALSE
  ) +
  theme_void()

Picking specific views

The views parameter lets you select which views to include and in what order. Check what's available with ggseg.formats::atlas_views():

#| label: aseg-views
ggseg.formats::atlas_views(aseg())

#| label: fig-aseg-select-views
#| fig-cap: "A subset of subcortical views selected by name."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain(
      views = c("sagittal", "axial_3", "coronal_3")
    ),
    show.legend = FALSE
  ) +
  theme_void()

Combine views with nrow or ncol for a custom grid:

#| label: fig-aseg-custom-grid
#| fig-cap: "Custom two-row grid with selected subcortical views."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain(
      views = c("sagittal", "axial_3", "axial_5", "coronal_3"),
      nrow = 2
    ),
    show.legend = FALSE
  ) +
  theme_void()

Grouping by slice type

The type ~ . formula groups views by their orientation -- all axial slices together, all coronal slices together, and so on. The type is extracted from the view name (everything before the first underscore):

#| label: aseg-type-group
#| eval: false
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain(type ~ .),
    show.legend = FALSE
  ) +
  theme_void()

Pre-processing with reposition_brain()

If you're using the geom_sf() workflow instead of geom_brain(), use reposition_brain() to rearrange the data before plotting. It takes the same arguments:

#| label: fig-reposition-brain
#| fig-cap: "Repositioned subcortical data plotted with geom_sf()."
atlas_data <- as.data.frame(aseg())

repositioned <- reposition_brain(
  atlas_data,
  views = c("sagittal", "axial_3", "coronal_3"),
  nrow = 1
)

ggplot(repositioned) +
  geom_sf(aes(fill = region), show.legend = FALSE) +
  theme_void()

Adding view labels

Use annotate_brain() to label each view with its name. For cortical atlases the label combines hemisphere and view (e.g. "left lateral"); for subcortical and tract atlases it uses the view name directly.

Store the position_brain() specification in an object so both layers share the same layout:

#| label: fig-dk-view-labels
#| fig-cap: "Cortical atlas with view labels."
pos <- position_brain(hemi ~ view)
ggplot() +
  geom_brain(atlas = dk(), position = pos, show.legend = FALSE) +
  annotate_brain(atlas = dk(), position = pos) +
  theme_void()

It works with any positioning — horizontal, vertical, grid, and formula layouts:

#| label: fig-aseg-view-labels
#| fig-cap: "Subcortical atlas with view labels in a two-row grid."
pos <- position_brain(nrow = 2)
ggplot() +
  geom_brain(atlas = aseg(), position = pos, show.legend = FALSE) +
  annotate_brain(atlas = aseg(), position = pos) +
  theme_void()

Text appearance is customisable through standard annotate() arguments:

#| label: fig-styled-labels
#| fig-cap: "View labels with custom styling."
ggplot() +
  geom_brain(atlas = dk(), show.legend = FALSE) +
  annotate_brain(
    atlas = dk(),
    size = 2.5,
    colour = "grey50",
    fontface = "italic"
  ) +
  theme_void()

Quick reference

| Atlas type | Options | |---|---| | Cortical | hemi ~ view, view ~ hemi, . ~ hemi + view, hemi + view ~ . | | Subcortical / Tract | "horizontal", "vertical", nrow, ncol, views, type ~ . |

ggseg documentation built on April 3, 2026, 5:06 p.m.