fsbrain

An R package for structural neuroimaging. Provides high-level functions to access (read and write) and visualize surface-based brain morphometry data (e.g. cortical thickness) for individual subjects and groups.

Fig.1: Visualization of sulcal depth for a subject in FreeSurfer standard space (fsaverage). See the source code to reproduce this image in an R notebook.

Fig.2: Visualization of statistical vertex-wise results (clusters) in FreeSurfer standard space (fsaverage) with a diverging colormap. See the source code to reproduce this image in an R notebook.

Fig.3: Visualization of statistical results per brain atlas region in FreeSurfer standard space (fsaverage) This uses the aparc atlas, but you can use any atlas. See the source code to reproduce this image in an R notebook.

About | Installation | Documentation | Unit tests | License | Citation | Visualization examples | Contributing

The fsbrain R package provides a well-tested and consistent interface to neuroimaging data in R. It supports reading, writing, and visualizing various kinds of raw data and statistical results on brain surfaces and volumes. While the package provides a very convenient interface for working with data arranged in the standard FreeSurfer directory structure (SUBJECTS_DIR), fsbrain is not limited to this layout or FreeSurfer file formats. You can load brain meshes, volumes, and data from a range of other neuroimaging software packages and visualize them.

The plots produced by fsbrain can be integrated into R notebooks or written to high-quality bitmap image files, ready for publication. By default, fsbrain uses the rgl package for rendering, which provides fast, hardware-accelerated 3D graphics based on OpenGL. As an alternative, fsbrain also supports the scimesh software renderer — a headless, GPU-free C++ renderer that produces identical static images without requiring X11, OpenGL, or a GPU. This is ideal for headless servers, HPC clusters, or macOS systems where XQuartz is broken.

• 2026-09-14: New fsbrain version 0.8.0 released on CRAN. See the CHANGES for more details.
• 2026-08-23: New fsbrain version 0.7.0 released on CRAN, see the CHANGES for details. With scimesh support.
• 2026-08-23: New documentation for the scimesh rendering backend: a new vignette (vignette("fsbrain_with_scimesh")) and an online notebook with pre-rendered figures that show how to configure fsbrain for headless, GPU-free static image export and how to use the export() API, including region- and vertex-based results and a workflow with manually loaded meshes.
• 2026-08-20: We have some new online documentation: example notebooks demonstrating 2 typical workflows of fMRI result visualization with fsbrain. View them online here.
• 2026-07-09: New fsbrain version 0.6.1 released on CRAN, see the CHANGES.
• 2026-07-08: New fsbrain version 0.6.0 released on CRAN, see the CHANGES.
• 2025-09-09: New fsbrain version 0.5.6 released on CRAN, see the CHANGES.
• 2024-02-03: New fsbrain version 0.5.5 released on CRAN, see the CHANGES.
• 2023-06-26: New fsbrain version 0.5.4 released on CRAN, see the CHANGES.
• 2022-12-22: We are looking for help! If you have a Mac and are interested in helping fsbrain development, please contact us by email or reply to #46 here on GitHub!
• 2022-02-13: New fsbrain version 0.5.3 released on CRAN, see the CHANGES.
• 2021-11-11: New fsbrain version 0.5.1 released on CRAN, see the CHANGES.
• 2021-09-16: New fsbrain version 0.5.0 released on CRAN, see the CHANGES.
• 2021-05-12: New fsbrain version 0.4.3 released on CRAN, see the CHANGES.
• 2021-03-28: New fsbrain version 0.4.2 released on CRAN, see the CHANGES.
• 2020-09-20: The preprint of our paper T. Schaefer, C. Ecker: fsbrain: an R package for the visualization of structural neuroimaging data' is now available on biorxiv.

You can find all releases in the releases section.

You can find the fsbrain package on CRAN, so all you need to do is:

install.packages("fsbrain");

The fsbrain package comes with some optional features. If you want all features:

install.packages("fsbrain", dependencies=TRUE);

If you are using a platform that defaults to building fsbrain from source, like Linux, and you are getting errors during installation about missing system dependencies, do not worry: just read INSTALL_FSBRAIN_FROM_SOURCE.md for instructions.

There are Docker images for fsbrain available on Dockerhub, see the fsbrain Dockerhub repo.

If you want the Dockerfiles, see docker/ in this repo.

If you work headless (HPC clusters, servers, CI runners, containers) or on recent macOS where XQuartz is broken, fsbrain's default rgl backend cannot open windows. Switch to the scimesh software renderer — a headless, GPU-free C++ renderer that produces identical static images without X11, OpenGL, or a GPU:

install.packages("scimesh");
options(fsbrain.renderer_backend = "scimesh");

Static image export (vislayout.from.coloredmeshes() and export()) now renders with scimesh. Interactive views (e.g., views = "si", "sr", "t4", "t9") and vis.rglwidget() still use rgl. Switch back at any time with options(fsbrain.renderer_backend = "rgl").

• How to use it: see the scimesh vignette (vignette("fsbrain_with_scimesh")) — what works, the limitations, and many worked examples.
• Why / when to use it, and alternatives: see README_HEADLESS.md, a decision guide for headless environments and broken-X11 macOS.

Interactive manipulation of rgl widgets and hosting them in Shiny apps (e.g. using vis.rglwidget() inside a Shiny app) require two extra packages that are only suggested by rgl and are therefore not installed automatically together with fsbrain:

install.packages(c("shiny", "manipulateWidget"))

The documentation can be accessed from within an R session after you have loaded the fsbrain package:

• There are several online R Markdown notebooks (like Jupyter Notebook in Python) that show various example plots in combination with the code used to produce them:

  • basic fsbrain example notebook: Live visualization of subject data
  • advanced fsbrain example notebook: Plotting group data
  • export API fsbrain example notebook: Exporting publication-ready plots
  • fsbrain with the scimesh rendering backend: Headless, GPU-free static image export

• Detailed R vignettes with explanations and examples for the functions of the package is included, run browseVignettes("fsbrain") to see the vignettes. You can also open the vignettes online — the GitHub Pages versions always reflect the latest development state (no new CRAN release required); the CRAN versions are updated on releases:

  • How to load and visualize surface-based neuroimaging data: vignette("fsbrain") or: read online (also on CRAN)
  • How to load and visualize volume-based neuroimaging data: vignette("fsbrain_vol") or: read online (also on CRAN)
  • The fsbrain FAQ: vignette("fsbrain_faq") or: read online (also on CRAN)
  • How to use the scimesh rendering backend: vignette("fsbrain_with_scimesh") or: read online (also on CRAN)

• The full API Documentation is at dfsp-spirit.github.io/fsbrain/reference/

• Online Notebooks including demo workflows for fMRI result visualization.

• Help for a specific function can be accessed in the usual R manner: ?<function>, where you replace <function> with a function name. Like this: ?group.morph.native.

• Run example(<function>) to see a live demo that uses the function <function>. Like this: example(group.morph.native).

• The unit tests that come with this package are essentially a list of examples that illustrate how to use the functions.

The fsbrain package is free software, published under the MIT license.

Note: The file LICENSE in this repository is a CRAN license template only (as required by CRAN) and does not contain the full MIT license text. See the file LICENSE_FULL for the full license text.

You can generate the citation for our fsbrain paper by typing the following command in R:

citation("fsbrain")

This currently outputs:

To cite fsbrain in publications use:

  Tim Schaefer, Christine Ecker (2020). fsbrain: an R package for the visualization of structural neuroimaging data. bioRxiv doi: 10.1101/2020.09.18.302935

A BibTeX entry for LaTeX users is

  @Misc{,
    title = {fsbrain: an {R} package for the visualization of structural neuroimaging data},
    author = {Tim Schaefer and Christine Ecker},
    year = {2020},
    url = {https://www.biorxiv.org/content/10.1101/2020.09.18.302935v1},
    doi = {10.1101/2020.09.18.302935},
  }

Other materials related to fsbrain:

• A poster on fsbrain has been presented at INSAR 2020 Annual Meeting: Abstract, ePoster viewer, PDF download

Want to see brains spin? Check this out. (WARNING: loads 8 MB webpage with animated gif).

You can also use fsbrain in a shiny app, see the demo code here and a live demo here on posit cloud: fsbrain in shiny app.

Volume visualization is not the main goal of fsbrain, but standard lightbox views and simple 3D views are supported. Have a look at the vignettes or the documentation for the volvis.lb function. You can find some example output here.

A particularly useful feature for quality assessment (QA) of FreeSurfer reconstructions is volvis.lb.with.surface(), which overlays the cortical surface boundary contours onto 2D MRI slices — similar to what freeview shows:

To see a combination of example figures and the code used to produce them, you should have a look at the example notebooks: getting started notebook and advanced examples notebook.

Please refer to CONTRIBUTING.md. For dev setup instructions, also read README_DEVELOPMENT.md.

If you have any question, suggestion or comment on fsbrain, please open an issue. If you want to contact me via email, please use the maintainer email address listed on the CRAN webpage for fsbrain.

Packages similar to fsbrain:

• ggseg by Athanasia Mowinckel and Didac Vidal-Piñeiro: Plotting of atlas-based neuroimaging data in R.
• cerebroviz by Ethan Bahl: Data mapping tool for visualizing spatiotemporal data in the brain.

Packages used by fsbrain:

• scimesh by Tim Schäfer: Headless C++ software renderer for 3D meshes. No GPU or X11 required.
• rgl by Daniel Adler, Duncan Murdoch et al.: OpenGL-based mesh renderer.
• oro.nifti by Brandon Witcher et al. : Loading and manipulation of brain volumes from NIFTI v1 files.
• freesurferformats by Tim Schäfer (me): Loading and writing various neuroimaging file formats and general mesh file formats, with a focus on FreeSurfer formats.
• gifti and cifti by John Muschelli: Read GIFTI and CIFTI format files.
• Rvcg by Stefan Schlager: Rcpp interface for the VCG Library.

fsbrain was written by Tim Schäfer