Skip to contents

geom_brain() handles data joining and positioning automatically, which covers most use cases. But because it owns the data pipeline, you can’t easily layer other sf geoms on top – things like geom_sf_label() or geom_sf_text() need direct access to the sf data.

This vignette shows how to work with brain atlases as plain sf objects, giving you full control at the cost of a few extra lines.

This is the one workflow that needs the sf package, which ggseg now treats as an optional dependency. Install it with install.packages("sf") if you don’t already have it. Everywhere else, geom_brain() plots the same atlases without sf.

library(ggseg)
library(ggplot2)
library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union

When you’d want this

Use the sf workflow when you need to:

  • Add region labels with geom_sf_label() or geom_sf_text()
  • Use ggrepel::geom_label_repel() for non-overlapping labels
  • Layer other sf geoms on the brain
  • Have full control over the data before it reaches ggplot

For everything else, geom_brain() is simpler.

Getting atlas data as sf

A brain atlas stores its geometry in the data slot. Reach it through the accessor rather than by list indexing:

ggseg.formats::atlas_geom(dk())
#> 
#> ── brain_polygons ──
#> 
#> Labels: 72
#> Views: inferior, lateral, medial, superior
#> Total points: 5391
#>                      label       geometry
#> 1               lh_unknown <df [113 x 5]>
#> 2               rh_unknown <df [111 x 5]>
#> 3            lh_precentral <df [150 x 5]>
#> 4  lh_lateralorbitofrontal  <df [89 x 5]>
#> 5      lh_superiortemporal <df [178 x 5]>
#> 6      lh_lateraloccipital <df [114 x 5]>
#> 7  lh_rostralmiddlefrontal <df [117 x 5]>
#> 8                lh_insula <df [132 x 5]>
#> 9       lh_parsopercularis  <df [69 x 5]>
#> 10        lh_supramarginal <df [117 x 5]>
#> ... with 62 more rows

The geometry column holds the polygons. This is a standard sf object, so any sf-compatible tool works with it.

Joining your data

Use brain_join() to merge your data with the atlas. It preserves the sf geometry and handles column detection:

some_data <- tibble(
  region = sort(unique(ggseg.formats::atlas_regions(dk())))[1:4],
  p = sample(seq(0, 0.5, 0.001), 4)
)

some_data |>
  brain_join(dk())
#> Merging atlas and data by region.
#> Simple feature collection with 185 features and 10 fields
#> Geometry type: MULTIPOLYGON
#> Dimension:     XY
#> Bounding box:  xmin: 0.899055 ymin: 0.0853615 xmax: 1938.834 ymax: 146.1192
#> CRS:           NA
#> First 10 features:
#>                         label     view  hemi                  region
#> 1                  lh_unknown inferior  left                    <NA>
#> 2                  lh_unknown  lateral  left                    <NA>
#> 3                  lh_unknown   medial  left                    <NA>
#> 4                  rh_unknown inferior right                    <NA>
#> 5                  rh_unknown  lateral right                    <NA>
#> 6                  rh_unknown   medial right                    <NA>
#> 7                 lh_bankssts inferior  left                bankssts
#> 8                 lh_bankssts  lateral  left                bankssts
#> 9                 lh_bankssts superior  left                bankssts
#> 10 lh_caudalanteriorcingulate   medial  left caudalanteriorcingulate
#>                              display      lobe atlas     type  colour     p
#> 1                               <NA>      <NA>    dk cortical    <NA>    NA
#> 2                               <NA>      <NA>    dk cortical    <NA>    NA
#> 3                               <NA>      <NA>    dk cortical    <NA>    NA
#> 4                               <NA>      <NA>    dk cortical    <NA>    NA
#> 5                               <NA>      <NA>    dk cortical    <NA>    NA
#> 6                               <NA>      <NA>    dk cortical    <NA>    NA
#> 7  banks of superior temporal sulcus  temporal    dk cortical #196428 0.172
#> 8  banks of superior temporal sulcus  temporal    dk cortical #196428 0.172
#> 9  banks of superior temporal sulcus  temporal    dk cortical #196428 0.172
#> 10         caudal anterior cingulate cingulate    dk cortical #7D64A0 0.406
#>                          geometry
#> 1  MULTIPOLYGON (((59.87309 38...
#> 2  MULTIPOLYGON (((309.1881 20...
#> 3  MULTIPOLYGON (((561.9354 46...
#> 4  MULTIPOLYGON (((1056.938 47...
#> 5  MULTIPOLYGON (((1376.635 14...
#> 6  MULTIPOLYGON (((1539.551 20...
#> 7  MULTIPOLYGON (((126.4784 10...
#> 8  MULTIPOLYGON (((373.1208 44...
#> 9  MULTIPOLYGON (((888.6798 41...
#> 10 MULTIPOLYGON (((632.9766 10...

The result is a standard sf object you can pass to geom_sf().

Plotting with geom_sf

some_data |>
  brain_join(dk()) |>
  ggplot() +
  geom_sf(aes(fill = p))
#> Merging atlas and data by region.
Brain plot using geom_sf after brain_join.

Brain plot using geom_sf after brain_join.

Repositioning views

With geom_brain(), you’d use position_brain(). In the sf workflow, use reposition_brain() instead – it transforms the geometry directly:

some_data |>
  brain_join(dk()) |>
  reposition_brain(hemi ~ view) |>
  ggplot() +
  geom_sf(aes(fill = p))
#> Merging atlas and data by region.
Repositioned brain views using reposition_brain() with geom_sf.

Repositioned brain views using reposition_brain() with geom_sf.

Same formula syntax, same results.

Adding labels

This is the main reason to use the sf workflow. Once you have repositioned sf data, you can layer any sf geom:

some_data |>
  brain_join(dk()) |>
  reposition_brain(hemi ~ view) |>
  ggplot(aes(fill = p)) +
  geom_sf(show.legend = FALSE) +
  geom_sf_label(
    aes(label = ifelse(!is.na(p), region, NA)),
    alpha = 0.8,
    show.legend = FALSE
  )
#> Merging atlas and data by region.
#> Warning: Removed 171 rows containing missing values or values outside the scale range
#> (`geom_label()`).
Brain regions with text labels overlaid using geom_sf_label.

Brain regions with text labels overlaid using geom_sf_label.

For crowded plots, ggrepel::geom_label_repel() avoids overlapping labels.

Faceting with grouped data

In the sf workflow, faceting requires group_by() before brain_join(). The grouping tells the join to replicate the atlas for each group:

some_data <- tibble(
  region = rep(sort(unique(ggseg.formats::atlas_regions(dk())))[1:4], 2),
  p = sample(seq(0, 0.5, 0.001), 8),
  group = c(rep("A", 4), rep("B", 4))
)

some_data |>
  group_by(group) |>
  brain_join(dk()) |>
  reposition_brain(hemi ~ view) |>
  ggplot(aes(fill = p)) +
  geom_sf(show.legend = FALSE) +
  facet_wrap(~group)
#> Merging atlas and data by region.
Faceted brain plots using the geom_sf workflow with grouped data.

Faceted brain plots using the geom_sf workflow with grouped data.

This step is only needed in the sf workflow. geom_brain() handles atlas replication automatically (see vignette("external-data")).