fsbrain: Utility Functions for the Analysis of Structural Neuroimaging Data in GNU R

In this document, we demonstrate some high-level functions for loading and analysing structural neuroimaging data preprocessed with FreeSurfer. FreeSurfer stores its output in a directory structure with fixed subfolder names. This package implements several high-level functions that allow the user to access surface-based brain structure data for large groups of subjects with very little code. It also supports the computation of statistics for individual brain structures or brain atlas regions for brain morphometry measures. Statistical analysis can then be performed using standard methods implemented in other packages.

Note: While this packages provides an abstract access layer to neuroimaging data, it does not implement file readers. It uses the ‘freesurferformats’ package in the background to parse the file formats.

Example data used in this document

We will use example data that comes with fsbrain throughout this manual. Feel free to replace the subjects_dir and subjects_list with data from your study.

library("fsbrain");
fsbrain::download_optional_data();
subjects_dir = fsbrain::get_optional_data_filepath("subjects_dir");
subjects_list = c("subject1", "subject2");

Accessing group data

This section explains how to load raw data for groups of subjects from files.

Morphometry data for groups

Use group.morph.native() and group.morph.standard() to load morphometry data for groups from morphometry data files (curv/MGH/MGZ).

Annotations for groups

Use group.annot() to load annotation data for groups from files.

Labels for groups

Use group.label() to load label data for groups from files.

Aggregating morphometry data

This section explains aggregation functions. These allow you to retrieve the mean, max, min, or whatever value over a number of vertices. Aggregation is supported on hemisphere level and on the level of brain atlas regions.

Aggregating group data over entire hemispheres

A single morphometry measure in native space

The fsbrain package provides a high-level interface to access data for groups of subjects. Here, we compute the mean thickness for each subject in native space:

A single morphometry measure in standard space

Here, we compute the mean thickness for each subject in standard space:

Several measures over several hemispheres in native space

When working with native space data for groups, vertex-wise comparison is not possible and one is often interested in aggregating data or summary statistics. Obtaining these for a group becomes easy with ‘fsbrain’:

The measure values are the mean thickness/area/volume over all vertices of the subject, computed from the respective native space morphometry files (e.g., ‘subject1/surf/lh.thickness’, ‘subject2/surf/lh.thickness’, and so on).

Note that you can get short format by setting ‘cast = FALSE’, which will result in a dataframe with the following columns instead:

  • subject_id
  • lh.thickness
  • rh.thickness
  • lh.area
  • eh.area
  • lh.volume
  • rh.volume

Several measures over several hemispheres in standard space

You could do the same in standard space with group.multimorph.agg.standard(), even though it’s less common as typically vertex-wise analysis is used in standard space. This requires that you pass the fwhm parameter to identify which smoothing value you want:

Other parameters exist to define the template subject, which defaults to ‘fsaverage’ in the example above.

Aggregating over atlas regions

Native space

Instead of looking at the full hemispheres, you may want to look at brain regions from some atlas (also called cortical parcellation). Examples are the Desikan atlas and the Destrieux atlas, both of which come with FreeSurfer.

The measure values are the mean thickness over all vertices of the respective region of the subject, computed from the respective native space morphometry files (e.g., ‘subject1/surf/lh.thickness’, ‘subject2/surf/lh.thickness’, and so on). The brain parcellation for the subject is read from its annotation file ( ‘subject1/label/lh.aparc.annot’ in this case).

Standard space

You could do the same in standard space with group.agg.atlas.standard(), even though it’s less common as typically vertex-wise analysis is used in standard space. This requires that you pass the fwhm parameter to identify which smoothing value you want, and that you have the template subject in the subjects_dir. The template subject defaults to fsaverage.

Other parameters exist to define the template subject, which defaults to ‘fsaverage’ in the example above.

Working with atlas data

You can use a mask to analyze (or exclude) data from certain regions. A typical usecase is to ignore the vertices from the medial wall in statistical analyses of the whole hemisphere, or to analyze only vertices from a specific label or atlas region. To archieve this, one could create a mask based on the ‘medial_wall’ region of the ‘aparc.a2009s’ atlas, and set all vertices in that region to NA for the subjects. Make sure to use functions that can work with NA values e.g., nanmean instead of mean) when working with the masked data.

Loading label files

One can load label files from disk using the subject.label() and group.label() functions.

Creating a label from an atlas region

One can use the label.from.annotdata() function on subject level, or the group.label.from.annot() function on group level to create a label from a brain parcellation.

Mapping one result value to each brain atlas region

Mapping a single value to an atlas region of a subject (usually a template subject like fsaverage) is useful to display results, like p values or effect sizes, on the brain surface. Here is an example script that uses fsbrain to do that:

This code will write an MGZ file that can be visualized in FreeView or Matlab/Surfstat.

Data visualization

This package comes with a range of visualization functions. They are based on OpenGL using the rgl package. See the rgl documentation for the requirements. Under MacOS, you will need to have XQuartz installed.

Rendering annotations (or brain parcellations based on an atlas)

Let’s first visualize an annotation:

This will give you an interactive window in which you can freely rotate a view similar to the one shown in the following screenshot:

Figure 1: Atlas regions visualized on a brain surface mesh. Annotation and mesh loaded with freesurferformats, and rendered using the rgl package.

Figure 1: Atlas regions visualized on a brain surface mesh. Annotation and mesh loaded with freesurferformats, and rendered using the rgl package.

You can also visualize morphometry data:

Figure 2: Cortical thickness data visualized on a brain mesh. Morphometry data and mesh loaded with freesurferformats, mesh rendered using the rgl package.

Figure 2: Cortical thickness data visualized on a brain mesh. Morphometry data and mesh loaded with freesurferformats, mesh rendered using the rgl package.

If you prefer a 2D view that shows brain regions from different viewports in cartoon style, you may want to try the ggseg package instead.