Introduction to ggseg3d

Brain segmentation results are easier to interpret when they look like a brain. ggseg3d takes a data frame with region names and renders it as an interactive 3D mesh — rotate, zoom, hover for labels — right in the browser.

Getting started

library(ggseg3d)

ggseg3d(hemisphere = "left") |>
  pan_camera("left lateral")
Left hemisphere of the Desikan-Killiany atlas, each cortical region in a distinct colour, viewed from the lateral side.
Left hemisphere of the Desikan-Killiany atlas, each cortical region in a distinct colour, viewed from the lateral side.

With no arguments, ggseg3d() plots the Desikan-Killiany atlas. The output is an htmlwidget: click and drag to rotate, scroll to zoom, hover to see region names.

Mapping data

Match your data to the atlas by region name, then point colour_by at the variable you care about:

library(dplyr)

some_data <- tibble(
  region = c("precentral", "postcentral", "insula", "superior parietal"),
  p = c(0.01, 0.04, 0.2, 0.5)
)

ggseg3d(.data = some_data, atlas = dk(), colour_by = "p", text_by = "p") |>
  pan_camera("right lateral")
Right hemisphere with four cortical regions coloured on a blue-to-red scale by p-value; unmatched regions shown in grey.
Right hemisphere with four cortical regions coloured on a blue-to-red scale by p-value; unmatched regions shown in grey.

text_by = "p" adds the p-value to the hover tooltip so you can inspect individual regions without a separate table.

Subcortical atlases

Cortical surfaces are only half the story. The aseg atlas covers subcortical structures, and add_glassbrain() wraps them in a translucent cortex for anatomical context:

subcort_data <- tibble(
  region = c("Thalamus", "Caudate", "Hippocampus"),
  p = c(0.2, 0.5, 0.8)
)

ggseg3d(.data = subcort_data, atlas = aseg(), colour_by = "p", na_alpha = .5) |>
  add_glassbrain()
Thalamus, caudate, and hippocampus coloured by p-value, visible through a semi-transparent cortical shell.
Thalamus, caudate, and hippocampus coloured by p-value, visible through a semi-transparent cortical shell.

Camera and background

pan_camera() sets the viewing angle. set_background() changes the canvas colour — handy for dark-themed slides:

ggseg3d(hemisphere = "left") |>
  pan_camera("left lateral") |>
  set_background("black")
Left hemisphere on a black background, cortical regions visible in their default atlas colours.
Left hemisphere on a black background, cortical regions visible in their default atlas colours.

Camera presets cover the standard anatomical views: "left lateral", "right medial", "left superior", and so on. For anything else, pass a list with eye coordinates.