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 simple 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. The results can be visualized on brain meshes (typically on a template subject like fsaverage) in various ways.

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");
subject_id = 'subject1';       # for function which use one subject only

Here, we manually defined the list of subjects. Typically, you would read the subjects and associated demographics or clinical data from a CSV file with standard R function like read.table, and you would have way more subjects of course.

Accessing group data

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

Morphometry data for groups

Many studies in neuroimaging use morphometry data, i.e., vertex-wise measurements like cortical thickness, volume, brain surface area, etc. These files are generated by FreeSurfer or computed from other data and stored in files like subject/surf/lh.area and rh.area for the left and right hemisphere, respectively.

Use group.morph.native() and group.morph.standard() to load morphometry data for groups from morphometry data files (in curv/MGH/MGZ formats). Here is an example that reads the cortical thickness in native space for all subjects of our study:

As this is native space data, the data for all subjects have different lengths because the subject’s brain meshes have different vertex counts. Therefore, groupdata is a named list. Let us determine the number of vertices and the mean cortical thickness of ‘subject1’:

In the following example, we read standard space data. This data has been mapped to the fsaverage template subject. In the process, the data gets smoothed with a filter at various settings. You have to decide which version of the data you are interested in. Here, we want the FWHM 10 data:

The data in standard space has the same number of entries for all subjects:

Note that 163842 is the number of vertices of the template subject fsaverage.

Labels for groups

Use group.label() to load label data for groups from files. A label is like a binary mask of vertex numbers, which defines a set of vertices. E.g., all vertices of a certain brain region. In the following examples, we load labels for our group of subjects:

Annotations for groups

An annotation, also known as a brain surface parcellation, is the result of applying an atlas to a subject. It consists of a set of labels (see above, one for each region) and a colortable.

Use group.annot() to load annotation 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:

Note that subject1 and subject2 in the test data are identical (2 is a copy of 1), so we get the same results for both.

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:

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

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.

Native space

This is typically done in native space, and here is an example:

We only showed the first 6 columns here.

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

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. Here is an example on the subject level:

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.It is common to visualize this on a template subject, like fsaverage. We do that for one hemisphere in the next example:

This code will write an MGZ file that can be visualized in FreeView or Matlab/Surfstat. Setting the parameter show_freeview_tip to TRUE as in the example will print the command line to visualize the data in FreeView.

The data can also be visualized directly in fsbrain, see the section Visualizing results of region-based analyses below. The functions listed there can also work with data from both hemispheres at once. See Figure 3B for example output.

Data visualization

This package comes with a range of visualization functions. They are based on OpenGL using the rgl package.

Visualizing different types of data

Visualizing annotations (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.

Figure 1: Atlas regions visualized on a brain surface mesh.

Visualizing morphometry data

You can also visualize morphometry data:

You want want to load the data first if you want to do advanced pre-processing or other computations before visualizing it:

Figure 2: Cortical thickness data visualized on a brain mesh.

Figure 2: Cortical thickness data visualized on a brain mesh.

Visualizing labels

To visualize a label, use the vis.subject.label function:

Visualizing results of region-based analyses

The result of a region-based analysis often is one result value (e.g., a p-value or an effect size) per atlas region. In the following example, we visualize such data on the fsaverage template subject, but you can use any subject of course.

See the help for the vis.region.values.on.subject function for more options, including the option to define the default value for the regions which do not appear in the given lists.

Figure 3: Various fsbrain visualizations. A Native space morphometry data. B Results of a region-based analysis. C An atlas.

Figure 3: Various fsbrain visualizations. A Native space morphometry data. B Results of a region-based analysis. C An atlas.

General visualization options

Different views

You can visualize the data in different views. So far, we have used only the si view. The following views are available:

  • si or single interactive view: renders a single instance of the mesh and allows the user to interactively explore the scene (rotate/zoom with the mouse). This view is good for live inspection of data during analysis.
  • sr or single rotating view: renders a single instance of the mesh rotates the camera around the mesh. Can be combined with rglactions (see section ‘Creating movies’ below) to create animated GIF images. This view is good for live inspection of data, and the resulting movies can be used in presentations.
  • t4 or tiled, 4 angles view: renders the meshes from four different angles. This kind of view is often used in publications.
  • t8 or tiled, 8 angles view: renders the meshes from eight different angles. This kind of view is often used in publications.

To change the view, set the view parameter in any visualization function. You can specify more than one view if needed:

See Figure 3A for an example of view t9 and Figure 3B for an example of view t4.

Changing the visualisation surface

By default, the data is visualized on the white surface. For some data, other surfaces may be more apppropriate. You can visualize the data on any FreeSurfer surface you have available. To do this, just set the surface parameter in any visualization function. The most commonly used surfaces and white, pial and inflated. Examples:

See Figure 4 for examples for the different surfaces.

Figure 4: Different visualization surfaces. A white surface. B pial surface. C inflated surface.

Figure 4: Different visualization surfaces. A white surface. B pial surface. C inflated surface.

Changing the resolution of figures (or other rgloptions)

The resolution of rgl windows is set in the call to rgl::par3d. You can pass arbitrary options to the call by specifying the parameter rgloptions when calling any visualization function. Here is an example that increases the resolution of the output window to 800x800 pixels and opens the window at screen position 50, 50:

See the documentation of rgl::par3d for all available options.

Note that for some OpenGL implementations, it may lead to artifacts or other problems if the window is not fully visible while actions like taking a screenshot or creating a movie are performed. In such a case you may have to adapt the position of the window on the screen (the first 2 parameters of the windowRect setting) to make it fully visible if parts of it are off-screen. This also means you should not perform other actions on the machine while a movie is being recorded, as taking away the focus from the rgl window or opening other windows on top of it may lead to artifacts.

Saving screenshots and creating GIF movies (and other rglactions)

The rglactions parameter can be passed to any visualization function to trigger certain actions during the visualization. These are actions like saving a screenshot or a movie or animation in GIF format. Some rglactions only make sense in certain views (e.g., recording a movie only makes sense in animated views, i.e., the sr view). Views will silently ignore actions which do not make sense for them.

The following rglactions are available:

  • Take a screenshot in PNG format. Key: “snapshot_png”. Value: string, the path of the output file, including the file extension. Path expansion is performed. Example: rglactions = list("snapshot_png"="~/fsbrain.png").
  • Record a movie. Only handled in rotating views like sr. Key: “movie”. Value: string, the base filename of the movie. The movie will be saved in your home directory, with file extension gif. Example: rglactions = list("movie"="fsbrain_rotating_brain")
  • Clip the data to remove outliers before visualization. Data smaller than the lower percentile and larger than the upper percentile will be set to the respective percentile value. Required to visualize data with outliers or extreme values, like mean of Gaussian curvature. Key: “clip_data”. Value: vector of length 2 with the lower and upper percentile. Example: rglactions = list("clip_data"=c(0.05, 0.95))

The actions can be combined, e.g., to clip the data and take a screenshot: rglactions = list("clip_data"=c(0.05, 0.95), "snapshot_png"="~/fsbrain.png").

Example: Creating a GIF animation (movie)

Here is an example that creates a GIF movie in your HOME directory:

The movie will be saved under the name ‘fsbrain_subject1_thickness_white.gif’ in your home directory. See the fsbrain project website for example output movies.

Postprocessing the movies

You can tweak the output GIF in whatever external software you like if needed. E.g., if you would like the animation to loop forever, you could use the convert command line utility that comes with ImageMagick. Run it from your operating system shell (not within R):

convert -loop 0 fsbrain_subject1_thickness_white.gif fsbrain_subject1_thickness_white_loop_inf.gif