Do you use ggplot to visualize imaging data on brain atlases? Welcome to ggbrat: brain atlases for ggplot2!
There is, of course, already the wonderful and popular ggseg package for this particular purpose (and subcortex_visualization for subcortex), but ggbrat offers something slightly different. While ggseg and subcortex_visualization provides prebuilt atlases and modified geoms, the focus of ggbrat is to provide tools for building the 2D atlases themselves (although it also comes with many prebuilt atlases). ggbrat builds two-dimensional brain atlases that work directly with ggplot2 and sf. It can turn cortical annotations, labelled (subcortical) surface meshes, volumetric NIfTI atlases, and labelled SVG drawings into plot-ready sf geometry, from whatever view angle you want. No more PNG snapshots and outlining; it is all automatic!
The origin of this package stemmed from me wanting to visualize my brain data using ggplot with a bit more cortical texture (I mean the brain looks cool, no?). And since I really don’t like doing things manually, and because the brain is cool from many different angles, I needed a way to be able to derive ggplot compatible atlases from any camera angle quickly.
Example surfaces/textures (plotted only using ggplot):

Example of four view angles rendered to 2D:
|
|
|
|

The package supports many atlases and file types. As long as you have a surface (or volume) with corresponding labels (FreeSurfer, GIFTI, or .vtp meshes), you can kind of build from whatever you want. For example, here is a surface rendering of the medial temporal lobe (shout out to @pyushkevich). The shading and region boundaries will, however, be better the more detailed the mesh is.
|
|
Furthermore, the package lets you create surface meshes from NIfTI atlases (I’ve only tested this with subcortical atlases as of yet), from which you can then build 2D atlases.
Here is an example of the aseg atlas:

Of course, if you prefer to visualize the subcortex in volume space, that is also possible. The package’s slice selector lets you choose whichever slices you want in your atlas.

There are also presets for both the surface-based view selector and its volumetric counterpart.

Have you drawn your own atlas in Inkscape, or some other vector-based illustration software that we don’t mention by name? No problem! If you’ve set up your drawing properly, you can just import it as a ready-to-go atlas file with the click of a button.

(courtesy of Anika Wuestefeld)
The name of the game
This package is about versatility, but within the limits of ggplot. As brain imagers favoring R (or perhaps ggplot), this is a tradeoff we have to deal with. Since ggplot is inherently a two-dimensional plotting library, and the brain is a three-dimensional object, ggplot will never be able to compete with proper 3D rendering software in terms of getting that sexy 3D look. However, what we lose in sexiness we gain in analytical versatility. As most of you know, ggplot is extremely versatile, especially with the numerous extensions built around it, making data exploration very easy compared to many other libraries. This was the reason that I did not want to wrap functionality around functions already handled by ggplot (and sf). All utilities and functionality that support geom_sf() can be used with ggbrat’s atlases.
To get the “3D look” for surface atlases, ggbrat can retain a density-sampled fraction of the original mesh vertices and plot them as an additional shade layer. That shade, overlays from other atlases, and even animations are still ordinary ggplot layers. See Plotting ggbrat atlases for the full examples.
So, the package separates atlas creation from atlas use. Any ggbrat atlas is just a Simple Features object/collection like any other. While creating these atlases (at least the surface-based ones) requires Python and specifically vtk (trust me, I tried to do everything in R, but sometimes R just says “no”), once an atlas has been built and saved as an RDS file, plotting and sharing it are ordinary R workflows and do not require Python and frankly do not even require this package anymore. You just load the atlas up, join it with your data, and plot it (it does require sf though).
[!NOTE] ggbrat is under active development. The function interface and downloadable resource catalog may change before the first stable release.
Quick start
Install the development version from GitHub:
# install.packages("pak")
pak::pak("jorittmo/ggbrat")Load a premade atlas and plot it:
library(ggbrat)
library(ggplot2)
yeo <- load_atlas("Yeo2011_7Networks_N1000")
ggplot(yeo$atlas) +
geom_sf(aes(fill = color), linewidth = 0.5) +
geom_sf(data = yeo$shade, size = 0.01, alpha = 0.05) +
scale_fill_identity() +
theme_void() 
load_atlas() downloads the atlas when necessary and keeps it in the user-specific ggbrat cache for next time.
For more detail, head over to:
Python dependencies
Plotting premade atlases, downloading resources, and using the volumetric and SVG functionality require R only. The following workflows additionally require Python 3.9 or newer:
-
build_atlas_surf(),brain_views(), andcapture_brain_view_presets()usenibabel,numpy,pandas,pyvista, andvtk. -
nifti_to_surface()usesnibabel,numpy,scipy,scikit-image, andvtk. -
templateflow_templates(),templateflow_get(),templateflow_metadata(), andtemplateflow_citations()usetemplateflow.
When one of these workflows first initializes Python, ggbrat displays an informational message. If the dependencies are not already available, reticulate may create or reuse an isolated managed environment and download them. This does not normally modify the system Python environment, but the first use can take several minutes, particularly for PyVista and VTK. An environment explicitly selected through reticulate continues to take precedence.
Contributing
ggbrat is still under active development and has not yet had a formal release. Testing, bug reports, documentation improvements, and code contributions are all very welcome.
Contributions of new atlases or better built atlases than the ones I quickly and automatically threw together is very welcome! Atlas contributions should preferably document potential original source, citation, license, input files etc
If you would like an atlas to be available through download_atlas() and load_atlas(), please open an issue or pull request that includes the finished RDS file or a reproducible build script and provenance and licensing metadata. The atlas can then be packaged as a downloadable resource and added to inst/extdata/resources.csv and inst/extdata/resource-files.csv.
Acknowledgements
All atlases and resources in this package comes from the enormous work of the neuroimaging community. Source citation should be available for each resource and you can find them by browsing:
If you use any of them in your work, please cite the original sources.
Available premade atlases can be found below. This will be updated as new atlases gets added, but I encourage you to crate your own 2D rendering instead! Some of the premade atlases (e.g. Brainstem_Navigator and SUIT) could use some more love in their creation (alternatively, just use subcortex_visualization).
| Name | Source |
|---|---|
| AICHA_subcortex | Joliot M, Jobard G, Naveau M, et al. (2015) |
| aparc | Desikan RS, Segonne F, Fischl B, et al. (2006) |
| aparc.a2005s | Fischl B, van der Kouwe A, Destrieux C, et al. (2004) |
| aparc.a2009s | Destrieux C, Fischl B, Dale A, Halgren E (2010) |
| aseg_subcortex | Fischl B, Salat DH, Busa E, et al. (2002) |
| Brainnetome_subcortex | Fan L, Li H, Zhuo J, et al. (2016) |
| Brainstem_Navigator | Bianciardi M and the Brainstem Imaging Laboratory (2024) |
| CIT168_subcortex | Pauli WM, Nili AN, Tyszka JM (2018) |
| HCP-MMP1 | Glasser MF, Coalson TS, Robinson EC, et al. (2016) |
| HO_FSSpace | Harvard Center for Morphometric Analysis and FMRIB Software Library. RRID:SCR_001476. |
| Melbourne_S1 | Tian Y, Margulies DS, Breakspear M, Zalesky A (2020) |
| Melbourne_S2 | Tian Y, Margulies DS, Breakspear M, Zalesky A (2020) |
| Melbourne_S3 | Tian Y, Margulies DS, Breakspear M, Zalesky A (2020) |
| Melbourne_S4 | Tian Y, Margulies DS, Breakspear M, Zalesky A (2020) |
| PALS_B12_Brodmann | Van Essen DC (2005) |
| PALS_B12_Lobes | Van Essen DC (2005) |
| Schaefer2018_1000Parcels_17Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_1000Parcels_7Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_100Parcels_17Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_100Parcels_7Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_200Parcels_17Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_200Parcels_7Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_300Parcels_17Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_300Parcels_7Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_400Parcels_17Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_400Parcels_7Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_500Parcels_17Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_500Parcels_7Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_600Parcels_17Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_600Parcels_7Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_700Parcels_17Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_700Parcels_7Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_800Parcels_17Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_800Parcels_7Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_900Parcels_17Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| Schaefer2018_900Parcels_7Networks_order | Schaefer A, Kong R, Gordon EM, et al. (2018) |
| SUIT_cerebellar_lobule | Diedrichsen J, Balsters JH, Flavell J, Cussans E, Ramnani N (2009) |
| Thalamus_HCP | Najdenovska E, Aleman-Gomez Y, Battistella G, et al. (2018) |
| Thalamus_THOMAS | Su JH, Thomas FT, Kasoff WS, et al. (2019) |
| Yeo2011_17Networks_N1000 | Yeo BTT, Krienen FM, Sepulcre J, et al. (2011) |
| Yeo2011_7Networks_N1000 | Yeo BTT, Krienen FM, Sepulcre J, et al. (2011) |