Source-linked AI summary
Visualisation of Brain Statistics with R-packages ggseg and ggseg3d
Athanasia M. Mowinckel, Didac Vidal-Piñeiro
TL;DR
Neuroimaging visualizations often fail to preserve the spatial dimension of brain atlas data. This tutorial presents ggseg, ggseg3d, and ggsegExtra for flexible 2D polygon and 3D mesh visualization in R, concluding that they facilitate parcellation-based visualization and dissemination while atlas creation remains difficult.
Problem
Existing visualization approaches and common statistical displays do not adequately represent the spatial relationships inherent in brain atlas data.
Method
The tutorial presents R packages that provide pre-compiled brain atlases, ggseg() for 2D polygon plots, ggseg3d() for 3D mesh plots, and ggsegExtra for additional atlases and contributions.
Results
The ggseg-packages provide flexible atlas visualization functions that integrate with ggplot2, plotly, interactive routines, and statistical analysis pipelines.
Takeaways & Limitations
The packages ease and streamline brain atlas visualization in R and support detailed, intuitive dissemination of neuroimaging results.
Takeaways & Limitations
Creating new 2D ggseg atlases is currently convoluted and difficult and requires manual intervention.
Abstract
from arXiv · showhide
There is an increased emphasis on visualizing neuroimaging results in more intuitive ways. Common statistical tools for dissemination, such as bar charts, lack the spatial dimension that is inherent in neuroimaging data. Here we present two packages for the statistical software R, ggseg and ggseg3d, that integrate this spatial component. The ggseg and ggseg3d packages visualize pre-defined brain segmentations as both 2D polygons and 3D meshes, respectively. Both packages are integrated with other well-established R-packages, allowing great flexibility. In this tutorial, we present the main data and functions in the ggseg and ggseg3d packages for brain atlas visualization. The main highlighted functions are able to display brain segmentation plots in R. Further, the accompanying ggsegExtra-package includes a wider collection of atlases, and is intended for community-based efforts to develop more compatible atlases to ggseg and ggseg3d. Overall, the ggseg-packages facilitate parcellation-based visualizations in R, improve and ease the dissemination of the results, and increase the efficiency of the workflows.
1 INTRODUCTION
Neuroimaging visualization should preserve the spatial relationships represented by brain parcellation atlases. The tutorial introduces R packages that provide 2D polygon and 3D mesh visualizations for brain atlas data.
- 1 INTRODUCTION: Brain parcellation atlases reduce whole-brain MRI information into finite sets of meaningful neurobiological regions.These regions reflect one or more brain features.
- 1 INTRODUCTION: Brain atlas results are most meaningfully visualized when projected onto brain representations that preserve spatial relationships across regions.Such projections provide reference points, ease readability, and guide interpretation.
- 1 INTRODUCTION: Existing R tools such as ggBrain and ggneuro display whole-brain image files but are not well-suited to brain atlas data.
- 1 INTRODUCTION: The ggseg, ggseg3d, and ggsegExtra packages provide pre-compiled brain atlas datasets for 2D and 3D visualization in R.ggseg uses polygons, while ggseg3d uses tri-surface mesh plots.
- 1 INTRODUCTION: The packages include data derived from the DKT cortical atlas and the aseg subcortical atlas, both implemented in neuroimaging software such as FreeSurfer.
2 TUTORIAL
The tutorial introduces ggseg, ggseg3d, and ggsegExtra and focuses on their main functions for plotting 2D polygon and 3D brain representations.
- 2 TUTORIAL: The tutorial familiarizes readers with the ggseg, ggseg3d, and ggsegExtra packages and their general use.
- 2 TUTORIAL: ggseg() plots 2D polygons, while ggseg3d() plots 3D brains using tri-surface mesh plots.
- 2 TUTORIAL: The tutorial focuses on the two main plotting functions and their use with brain atlas data.
2.1 Plotting polygon data (ggplot2)
ggseg() plots brain atlas polygons as flexible ggplot2 objects, supporting atlas-specific views, statistical data integration, color mapping, and faceted group comparisons.
- 2.1 Plotting polygon data (ggplot2): ggseg() automatically plots the DKT atlas as 2D polygons and can be combined with ggplot2 features because it wraps geom_polygon().The default plot is a simple brain representation without extra information.
- 2.1 Plotting polygon data (ggplot2): Cortical atlas plots can vary by hemisphere, medial or lateral view, and stacked position, while subcortical atlases support axial, sagittal, and coronal views.
- Using own data with fill and colour: ggseg() accepts geom_polygon() arguments such as fill and colour, either as fixed settings or through ggplot2 aesthetic mappings.
- Using own data with fill and colour: Supplying area to fill applies a discrete segment palette, with the DKT default corresponding to the FreeSurferColorLut scheme.
- Using own data with fill and colour: Input data are merged with atlas polygons through matching columns such as label or area, and must use a compatible long format.A hemisphere column can be used when data cover only one hemisphere.
- Using own data with fill and colour: Supplied data can drive aesthetic mappings and standard ggplot2 functions can modify titles, legends, scales, themes, and color schemes.
- Creating subplots: Group-specific brain statistics can be displayed with ggplot2 facet_wrap or facet_grid after organizing group observations in long format and grouping them with dplyr.Figure 5 illustrates faceting for Young and Old groups.
- Creating subplots: The same concepts apply to the aseg atlas, except hemisphere and view arguments are superfluous for subcortical atlases.
2.2 Plotting 3D mesh data
ggseg3d provides interactive 3D brain-atlas visualizations using tri-surface meshes and plotly, with options for surfaces, coloring, camera views, and glass-brain context.
- Motivation: ggseg3d addresses the difficulty of locating three-dimensional and subcortical regions in flattened 2D brain representations.It uses interactive tri-surface mesh plots to display, view, and print 3D atlases in R.
- Implementation: ggseg3d uses plotly-based tri-surface meshes, with more complex data structures than ggplot2 polygon atlases.The package supports brain inflation, glass brains, camera locations, and other 3D visualization options.
- Surface options: Cortical ggseg3d atlases provide white, semi-inflated LCBC, and inflated grey-matter surfaces.The LCBC surface is a semi-inflated white-matter surface based on the fsaverage5 template subject; subcortical atlases have only one surface.
- Data preparation: Users can inspect nested atlas data by selecting a surface and hemisphere, unnesting the mesh data, and matching regional identifiers to atlas labels.The mesh column contains lists of vectors needed to create each tri-surface region; label, annot, and area provide matching names.
- Styling and interaction: ggseg3d maps a supplied data column to segment colors and can add the same or another column to plotly hover text.Custom palettes accept HEX codes, R color names, or named numeric vectors with explicit breakpoints, including a separate NA color.
- Subcortical visualization: A glass brain provides spatial context for subcortical structures and is controlled by hemisphere, color, and opacity.Additional plotly functions can modify 3D representations, and atlas snapshots can be saved with orca.
2.3 Additional atlases
ggsegExtra extends ggseg and ggseg3d beyond their built-in dkt and aseg atlases by collecting additional atlas datasets for community expansion.
- Built-in atlases: The built-in ggseg and ggseg3d atlases cover 2D and 3D variations of the dkt and aseg parcellations.ggsegExtra adds further datasets because these are only two among many meaningful brain-segmentation schemes.
- Community atlas repository: ggsegExtra is intended as a community-expanded repository for new and informative atlases published as neuroimaging methods progress.Figure 10 shows four example datasets from the library plotted with ggseg() and ggseg3d().
3 DISCUSSION
The ggseg packages provide simple, extensible brain-atlas visualizations that add spatial structure to statistical workflows in R. Their niche is complementary rather than competitive: atlas-based plots integrate readily with analysis pipelines but remain constrained by flattened 2D polygons and parcellation-limited 3D meshes.
- Discussion: The ggseg packages complement existing R and software-specific visualization tools rather than claiming superiority over them.The authors identify simplicity and compatibility with statistical analysis pipelines as the package niche.
- Discussion: The packages combine brain-atlas collections, tailored plotting functions, and customizable color features for visualizing parcellated data.Their atlas data derive from established cortical and subcortical parcellations.
- Discussion: ggseg() wraps ggplot2 polygons, while ggseg3d() wraps plotly tri-surface meshes for 2D and 3D brain visualization.Both wrappers can be extended with arguments from their respective plotting environments.
- Discussion: Users can adapt plots and convert data into atlas formats, while contributing additional atlases through ggsegExtra.These features support customization and community expansion of the atlas repository.
- Discussion: The packages originated from a need to inspect cortical-thickness trajectories while retaining spatial and time-varying information beyond classical 2D plots.The motivating use case involved lifespan trajectories across brain regions.
- Discussion: The package structure may also be adapted to scientific fields that benefit from displaying data across a spatial dimension.The authors note that such adaptation has already been applied in gganatogram.
4 PLANNED PACKAGE IMPROVEMENTS
The planned improvements target atlas creation, which is currently convoluted and requires manual intervention. A future pipeline is intended to automate extraction and organization of atlas components while encouraging community contributions.
- Planned package improvements: Creating ggseg 2D atlases is currently difficult, convoluted, and dependent on manual intervention.The authors identify this workflow as the central package-development constraint.
- Planned package improvements: The planned pipeline will call specialized tools to detect polygon vectors or mesh segments from MRI parcellation images.Named tools include FSL, FreeSurfer, and ImageMagick.
- Planned package improvements: The extracted components will be organized into valid ggseg and ggseg3d atlas formats.The intended result is a simpler, more straightforward atlas-creation workflow.
- Planned package improvements: Users are encouraged to contribute additional brain atlases to the ggsegExtra repository.The contribution model is part of the planned expansion of atlas coverage.
5 CONCLUSION
The tutorial presents ggseg packages as R tools for visualizing brain statistics through parcellation atlases. They combine with interactive routines and statistical pipelines, with intended usefulness extending across fields and structures.
- Conclusion: The ggseg packages visualize brain statistics through brain parcellation atlases in R.The tutorial introduces the packages as tools for neuroimaging visualization.
- Conclusion: The visualization tools combine with interactive routines and diverse statistical analysis pipelines.This integration is presented as a practical feature of the packages.
- Conclusion: The authors hope the tools support neuroscientists and inspire applications across a wide variety of fields and structures.The stated scope extends beyond the immediate neuroimaging examples.
6 AUTHOR CONTRIBUTIONS
The paper credits distinct contributions to the tool’s conception, visualization scripts, package development, mesh functionality, and related pipeline work.
- Author contributions: Didac Vidal-Piñeiro generated the tool idea and initial visualization scripts.He also converted neuroimaging images into ggseg-like polygon and mesh data.
- Author contributions: Athanasia M. Mowinckel adapted the scripts into a package and continued developing user-friendly functions.The supplied passage attributes ongoing package development to her.
- Author contributions: Mowinckel conceived and added plotly-based mesh functionality and developed the associated pipeline.These contributions concern the 3D visualization capability.
9 FUNDING
The work received funding from EU Horizon 2020, the European Research Council, and the Norwegian Research Council.
- EU Horizon 2020 funded the work through the Lifebrain project.The project was supported under grant agreement 732592.
- The European Research Council supported the project through Starting and consolidator grants.The listed grant agreements include 283634, 313440, 771355, and 725025.
- The project also received funding through multiple Norwegian Research Council grants.
10 PRIOR VERSIONS
Earlier tutorials by Athanasia Monika Mowinckel covered ggseg creation and functionality.
- Mowinckel’s 2018a tutorial addressed ggseg creation.
- Mowinckel’s 2018b tutorial addressed ggseg functionality.
- The tutorials provide related material on ggseg.