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

knitr::opts_chunk$set(echo = TRUE)
rgl::setupKnitr()

This document shows how to use different options of the fsbrain export API fpr producing publication-ready figures from data visualized on a the surface of a single subject. It is basically a demonstration of the export function.

Example data

First we specify a subjects dir and the subject we want to use. Feel free to replace this with your data.

library('fsbrain')
sjd = '~/data/subject1_only'
sj = 'subject1'

If you do not have any data but still want to follow this tutorial, you can download and use the fsbrain example data like this instead:

library('fsbrain')
download_optional_data()
download_fsaverage(accept_freesurfer_license = TRUE)
sjd = get_optional_data_filepath("subjects_dir");
sj = 'subject1'

Now set the figure size if needed. Currently 800x800 is the default.

fsbrain.set.default.figsize(700, 700);

Eporting publication-ready plots

A basic example

The export function provides a high-level interface to export plots. It works on a coloredmeshes instance, which is returned by all live visualization functions in fsbrain and represents two brain meshes along with some metadata like the per-vertex data, a colormap, and resulting per-vertex colors. See the help for the `fsbrain::hemilist function for details if you need them.

Note: The function export is an alias for the vis.export.from.coloredmeshes function, which was the name used before fsbrain version 0.5.0. So if you do have an older version of fsbrain, simply replace the function name for the following examples.

Here is an example that obtains the coloredmeshes instance (called cm here) by running vis.subject.morph.standard.

cm = vis.subject.morph.standard(sjd, sj, 'thickness', fwhm='10', cortex_only = T, views=NULL);
img = export(cm);

Note that we suppress the output of the vis.subject.morph.standard function with views=NULL here, because this is faster and we are only interested in the return value of the function. Suppressing the rendering is optional, but we will do it throughout this document.

You could also get the cm from others functions like vis.subject.morph.native, vis.subject.label, vis.subject.annot, vis.color.on.subject, vis.data.on.subject, and so on (which are the topic of the introductory notebook and not repeated here).

The image gets exported as a PNG file into the current working directory by default, and you can set the 'output_img' parameter to save it wherever you want. One can also show it directly:

img;

In the following examples, we will use different data by obtaining our cm value from different visualization functions so that this document does not look too boring. However, we are mainly interested in, and will only comment on, the different parameters passed to the export function.

Adding a description text above the colorbar and changing the output file location

This is especially important if you export lots of figures so you do not confuse them later:

cm = vis.subject.morph.standard(sjd, sj, 'sulc', fwhm='10', cortex_only = T, views=NULL);
img = export(cm, colorbar_legend='Sulcal depth [mm]', output_img = "~/sulcal_depth.png");

img;

Changing the views and output file location

The views can be customized by passing one or more view strings via the view_angles parameter. You can get a list of all valid view strings by calling get.view.angle.names:

get.view.angle.names("all")

Let's use them to modify the views:

cm = vis.subject.annot(sjd, sj, 'aparc', views=NULL);
img = export(cm, view_angles = c("sd_medial_lh", "sd_medial_rh"));

img;

The layout of the individual tiles is automatically determined by the number of views that one requests: 4 will be organized as 2x2 (see above), 8 will be organized like this:

cm = vis.subject.morph.native(sjd, sj, 'curv', cortex_only = T, views=NULL, rglactions=list('trans_fun'=clip.data));
img = export(cm, view_angles = get.view.angle.names(angle_set = "t8"), colorbar_legend='Mean curvature [mm^-1]');

img;

For all other numbers, a vertical strip of images will be produced. One can always force this strip, instead of the grid-like default behavior described above, by setting the grid_like parameter to FALSE:

cm = vis.subject.morph.native(sjd, sj, 'jacobian_white', cortex_only = T, views=NULL, rglactions=list('trans_fun'=clip.data), makecmap_options = list('colFn'=viridis::rocket));
img = export(cm, view_angles = get.view.angle.names("t4"), grid_like = FALSE, colorbar_legend='Jacobian white');

img;

The colorbar

The position of the colorbar can be set using the horizontal parameter. It can be plotted horizontally (horizontal = TRUE, the default), vertically (FALSE), or skipped (NULL).

cm = vis.subject.morph.standard(sjd, sj, 'sulc', fwhm='10', cortex_only = T, views=NULL);
img = export(cm, colorbar_legend='Sulcal depth [mm]', horizontal = FALSE);

img;

Note that plotting a colorbar is only possible if the cm instance contains colorbar information. This will not be the case if it was obtained by visualizing annotations (vis.subject.annot) or custom colors (vis.color.on.subject). The request to draw a colorbar will be ignored in such a case.

Changing the background color

It's possible to change the background color of the plot with the background_color parameter. Just be sure to use hex color strings like '#DDDDDD' instead of color names like 'gray', because these names are ambiguous and their interpretation differs between R and ImageMagick, both of which are using to produce these plots.

cm = vis.subject.morph.standard(sjd, sj, 'sulc', fwhm='10', cortex_only = T, views=NULL);
img = export(cm, c("sd_medial_lh", "sd_medial_rh"), background_color = '#000000', horizontal = NULL);

img;

Plotting with transparent background

To the best of my knowledge, rendering with a transparent background is not supported by rgl (which makes some sense if you consider that it draws to a graphics window -- you have to fill the screen position with something). However, since having a transparent background is very convenient when creating figures for publications, fsbrain offers a post-processing option to achieve this by using the transparency_color parameter. It works by first setting the background to a custom color, and later mapping that color in the output image to transparency for the PNG export.

cm = vis.subject.morph.standard(sjd, sj, 'sulc', fwhm='10', cortex_only = T, views=NULL);
img = export(cm, view_angles = c("sd_medial_lh", "sd_medial_rh"), transparency_color = '#FFFFFF');

img;

Some notes on selecting the transparency_color value:

• You should always try setting the transparency color to '#FFFFFF' (white) first, as shown in the example above.
• The transparency_color has to be an RGB color, i.e., it cannot have an alpha value (if it is an RGBA color, the alpha part is silently ignored by RGL it seems).
• The transparency_color can be almost any RGB color, but (1) it should not occur in the brain surface visualization to prevent transparent parts in the brain after post-processing. And (2) because of anti-aliasing, the color may slightly affect the border pixels of the rendered brain surfaces, so a neutral color like '#FFFFFF' (for white) or some gray value like '#DDDDDD' is maybe more suitable than a hot pink. At high resolution, this is hardly noticeable though.
• It is NOT required to manually set the background_color to the transparency_color, this is done automatically.

Learning more

To learn more, read the vignettes:

browseVignettes('fsbrain');

In general, the vignettes are a great way to get started with fsbrain. You can also read them online at CRAN, they are linked on the fsbrain page on GitHub.

dfsp-spirit/fsbrain documentation built on Nov. 28, 2024, 10:29 a.m.