Welcome to the ggseg website

Welcome to the new ggseg website. This site provides documentation, resources, and news about the ggseg suite of R packages for brain atlas visualization.

Why brain atlas visualization?

Neuroimaging research frequently involves mapping statistical results onto brain regions defined by anatomical or functional atlases. Whether you’re showing which brain areas respond to a task, where structural differences exist between groups, or how connectivity patterns vary across individuals, visualizing these results on a brain surface helps communicate findings clearly.

The ggseg suite brings brain atlas visualization into the tidyverse ecosystem, making it easy to create publication-ready figures with the familiar grammar of graphics.

What is ggseg?

The ggseg ecosystem consists of three layers:

Core packages provide the visualization engine:

• ggseg - 2D brain atlas plots as ggplot2 geoms
• ggseg3d - Interactive 3D brain atlas plots using plotly
• ggsegExtra - Tools for creating and validating custom atlases

Atlas packages distribute brain atlas data as installable R packages. Each atlas package contains polygon data for 2D plots and/or mesh data for 3D visualization.

Atlases are the individual brain parcellations within each package. A single package might contain multiple related atlases (e.g., different resolutions or variants).

Example: 2D visualization

The core ggseg package provides geom_brain() for plotting brain data with ggplot2:

library(ggseg)

Loading required package: ggseg.formats

library(ggplot2)

ggplot() +
  geom_brain(atlas = dk, mapping = aes(fill = region), show.legend = FALSE) +
  theme_void()

Basic ggseg plot showing the Desikan-Killiany atlas

Map your own data by joining it to the atlas:

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

someData <- tibble(
  region = c(
    "superior frontal",
    "precentral",
    "lateral orbitofrontal",
    "parsopercularis",
    "paracentral",
    "pericalcarine"
  ),
  p = sample(seq(0, 0.05, by = 0.001), 6)
)

someData |>
  ggplot() +
  geom_brain(
    atlas = dk,
    position = position_brain(hemi ~ view),
    aes(fill = p)
  ) +
  scale_fill_viridis_c(option = "inferno", direction = -1) +
  theme_void() +
  labs(fill = "p-value")

merging atlas and data by 'region'

Warning: Some data not merged properly. Check for naming errors in data:
  label view  hemi  region    lobe                  geometry atlas type  colour
  <chr> <chr> <chr> <chr>     <chr>     <GEOMETRYCOLLECTION> <chr> <chr> <chr> 
1 <NA>  <NA>  <NA>  parsoper… <NA>  GEOMETRYCOLLECTION EMPTY <NA>  <NA>  <NA>  
# ℹ 1 more variable: p <dbl>

Warning: Some data not merged. Check for spelling mistakes in: region p 185
parsopercularis 0.007

Mapping custom data to brain regions

Example: 3D visualization

For interactive 3D plots, ggseg3d uses plotly:

library(ggseg3d)

ggseg3d(atlas = dk) |>
  pan_camera("right lateral")

Interactive 3D brain visualization

The atlas ecosystem

The ggseg ecosystem includes atlases covering:

• Cortical parcellations - Desikan-Killiany, Destrieux, Glasser, Schaefer, and more
• Subcortical structures - aseg
• White matter - JHU tracts, tracula pathways
• Functional networks - Yeo networks, Gordon parcellation, AICHA

Browse all available atlases on the Ecosystem page.

Getting started

Install the core packages from R-universe:

install.packages(
  c("ggseg", "ggseg3d", "ggsegExtra"),
  repos = c(
    "https://ggseg.r-universe.dev",
    "https://cloud.r-project.org"
  )
)

Then install any atlas packages you need:

install.packages(
  "ggsegYeo2011",
  repos = c(
    "https://ggseg.r-universe.dev",
    "https://cloud.r-project.org"
  )
)

Check out the documentation for tutorials and vignettes.

Stay updated

• Follow GitHub Discussions for community help and announcements
• Report issues on individual package repositories
• Star the repos to show support