README.md

In dfsp-spirit/nitools: Managing and Visualizing Brain Surface Data

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.

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

About

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. The rgl renderer used by fsbrain provides fast, hardware-accelerated rendering based on the OpenGL standard.

News

• 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.

Installation

Recommended: install the stable fsbrain version from CRAN

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

install.packages("fsbrain");

In case something goes wrong, don't worry. Just install the missing system dependencies and retry.

Risky: install the dev version of fsbrain with the latest features

This version is not guaranteed to be in a usable state, try at your own risk and run the tests before using it.

From an R session:

install.packages(c("devtools", "knitr", "markdown", "rmarkdown", "testthat", "qpdf"));
devtools::install_github("dfsp-spirit/fsbrain", build_vignettes=TRUE);

System dependencies

A system dependency is a non-R software that is needed for the installation of a package. System dependencies cannot be installed automatically using the R package system, so you need to install them manually or using the package manager of your operating system.

The fsbrain package itself does not have any system dependencies, however, it uses rgl for rendering. You can check the SystemRequirements section on the rgl page at CRAN for the full list of rgl dependencies or read on. To get GIFTI format support, you will also need libxml2-dev.

To install the system dependencies for rgl and xml2:

Linux System dependencies (or: building from source)

R packages are compiled from source by default under Linux, so you need some development libraries. Before installing fsbrain, run the following command in your system shell (not in R):

• for deb-based Linux distributions (Debian, Ubuntu, ...):

sudo apt-get install libmagick++-dev libx11-dev libgl1-mesa-dev libglu1-mesa-dev mesa-common-dev libfreetype6-dev libxml2-dev libssh-dev libcurl4-openssl-dev libgfortran4

• for rpm-based Linux distributions (Fedora, CentOS, RHEL, ...):

sudo yum install ImageMagick-c++-devel libX11-devel mesa-libGLU-devel freetype-devel libxml2-devel

If you want to compile the package under any other operating system, you will need the libraries as well, of course.

MacOS System dependencies

Recent MacOS versions do not ship with an X11 environment. You will have to install the xquartz X11 system if you do not have it already. If you want to create GIF movies, make sure you have imagemagick installed (easiest via homebrew: brew install imagemagick@6).

Windows Installation Hints

Under Windows 10, it seems that you will need to install these two packages manually via the install.packages command: shiny and manipulateWidget.

Installation via Docker

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

Documentation

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

• There are two 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

• Detailed 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 vignette directly:

• How to load and visualize surface-based neuroimaging data: vignette("fsbrain") or: read online at CRAN
• How to load and visualize volume-based neuroimaging data: vignette("fsbrain_vol") or: read online at CRAN

• The fsbrain FAQ: vignette("fsbrain_faq") or: read online at CRAN

• 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.

Unit tests and Continuous integration

This package comes with lots of unit tests. To run them, in a clean R session:

library(devtools)
library(fsbrain)
devtools::check()

Continuous integration results:

AppVeyor CI under Windows

GitHub Actions, Ubuntu Linux and MacOS (Note: Currently this is always "failing" because of a warning caused by the rgl package when running headless. So the simlpe "passing"/"failing" status is useless, and one needs to follow the link to check the relevant CI results in detail.)

License

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.

Citation and Publications

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

Visualization examples

The fsbrain package support visualizations of different data, and all data can be displayed in one or more views. The figure below shows some examples for surface-based data:

Fig.2: Example output for the fsbrain interactive visualization functions.

• Subfigure A shows the visualization of raw morphometry data (cortical thickness) from native space on the white surface of a subject. The view shows the data in tiles from 8 different angles.
• Subfigure B illustrates arbitrary data (p-values in this case) visualized on the regions of the Desikan atlas, using the surface of the fsaverage (standard space template) subject from FreeSurfer. The view shows the data in tiles from 4 different angles.
• Subfigure C displays the regions of the Desikan atlas on the white surface of a subject. The colors were loaded from the respective annotation file. The view shows the data in tiles from 4 different angles.

What is displayed (morphometry data, atlas regions, arbitrary other data), on which surface it is displayed, and how it is displayed (a single interactive view, 4 tiles, 9 tiles) is independent and can be selected as needed in fsbrain.

Here is a second figure, showing the same data (the mean curvature at each vertex) displayed on 3 different surfaces of a subject: A white surface, B pial surface, C inflated surface.

The next figure illustrates some options to visualize your results with different backgrounds. A Clusters on the white fsaverage surface with sulc background. B Region-wise p-values with curv background, inflated fsaverage surface. C A background color layer displaying outlines of aparc atlas regions in the respective colors, inflated demo subject surface.

Animations and videos

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

Volume visualization

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.

Example Notebooks

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.

Contributing

Please refer to CONTRIBUTING.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.

Related R packages

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:

• 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.

Author

fsbrain was written by Tim Schäfer

dfsp-spirit/nitools documentation built on Jan. 26, 2024, 8:24 p.m.