brain_join: Join user data with a brain atlas

In ggseg: Plotting Tool for Brain Atlases

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

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

ggseg documentation built on June 22, 2026, 9:09 a.m.