The fsbrain software is designed to be used with the output of FreeSurfer. Running recon-all on your T1w MRI scan results in a directory structure full of different files and file types for each subject. The fsbrain library uses knowledge on this directory layout to load the proper data.
However, while designed primarily with FreeSurfer in mind, fsbrain is not limited to FreeSurfer output, see below.
The fsbrain library uses freesurferformats to load a variety of neuroimaging file formats, including data exchange formats used by other brain imaging software. See the freesurferformats website for the full list.
You can use freesurferformats directly to load the data, then pass it to fsbrain. See the next question for an example.
Yes, the computational anatomy toolbox (CAT12) for SPM writes surfaces in GIFTI format and the morphometry data in curv format, both formats are supported by fsbrain. After running CAT12 surface measure computation on your subject subject1, you should have the following files in the surf/ subdir:
Try the following to visualize the gyrification data for the left hemisphere in fsbrain:
To increase the output resolution, you need to increase the size of the rgl rendering device. To do this globally, before you call any fsbrain rendering function:
This instructs rgl to create new rendering devices at screen position 20, 20 (close to the upper left corner) with a size of 1800x1200 pixels.
Alternatively, you can control the size when calling an fsbrain visualization function by passing the same information in the optional rgloptions parameter, like this:
Note that fsbrain renders images, which means the output is pixel-based (i.e., bitmap as opposed to vector graphics). To get high quality output, you need to increase the size of the rgl rendering device, as explained in the last question.
To save the plot to a file in PNG format, you can use an rglaction:
rgla = list('snapshot_png'='~/subject1_thickness.png');
vis.subject.morph.native('~/mysubjects_dir', 'subject1', 'thickness', rglactions=rgla);This opens the plot in a window as usual and also saves it in PNG format to the file subject1_thickness.png in your home directory.
Pass a colormap function to any visualization function that supports the makecmap_options parameter, as entry colFn like illustrated below:
mkc = list('colFn'=viridis::viridis);
vis.subject.morph.native('~/mysubjects_dir', 'subject1', 'thickness', makecmap_options=mkc);In that example, we used the popular viridis colormap. In R, it is available from the viridis package. If you don’t have it, you can install it with:
Of course, you can use any colormap function you want, currently the only limitation is that it should accept an integer parameter: the requested number of colors.
The exact number of colors that will be requested depends on your data, and if the colormap you want only supports very few colors, you can use a wrapper function to interpolate. Here is an example for the very popular RColorBrewer package. Some of its colormaps have less than 10 colors, which is usually not enough for neuroimaging data. Here we wrap the ‘Blues’ palette, which has 9 colors:
The impression that the numbers of colors in the colorbar is lower than in the rendered image is a consequence of the rendering process: the lighting (shadows, highlights) and the material properties (glossyness, partial transparency) have an effect on the appearance of colors in the rendered image.
You can set the parameter n in the makecmap_options (see above) to request more colors, which will lead to a smooth colorbar.
mkc = list('n'=100L);
vis.subject.morph.native('~/mysubjects_dir', 'subject1', 'thickness', makecmap_options=mkc);This also means that more colors are used in the rendered image, but the effect will be less noticable.
Yes, see the answer to the next question for details.
Yes, use the vis.colortable.legend function. You can pass an annotation or a color lookup table, and it will create a plot that shows the colors and the structure (or region) names. The output will be a separate plot, so you can use standard R methods to save it in vector formats like PDF for best quality.
Hint: you can load a color lookup table with freesurferformats::read.fs.colortable.
While this is not possible in rgl, fsbrain provides the vislayout.from.coloredmeshes function to achieve this using Image Magick. You need to have the suggested ‘magick’ package installed for this to work. The function renders separate images, crops the output figures to remove the background, then merges the seperate cropped images into a final output image and saves it as a PNG file. Here is a usage example:
# To get coloredmeshes return value only, ignore the visualization:
cm = vis.subject.morph.native(sjd, sj, 'thickness', makecmap_options = list('n'=100), cortex_only = T);
# Produce high quality tight layout:
vislayout.from.coloredmeshes(cm);Note that your output resolution settings (see question above) now count for each of the single images. This means that you will get quite high resolution output in combination with the tight layout. This makes the function ideal for producing plots for publications.
You can adjust various settings, e.g., change the rendering stlyle, select different views, and save it to a custom file name in your home directory:
output_brain_img = "~/fig1_brain.png";
vislayout.from.coloredmeshes(cm, view_angles = get.view.angle.names(angle_set='t9'), output_img = output_brain_img);It is also possible to plot a separate colorbar image and combine that with the tight layout brainview image. Note that the settings for the colorbar are stored in the coloredmeshes, and can be adjusted by altering the initial call to vis.subject.morph.native (or whatever visualization function you use) above.
output_cbar_img = "~/fig1_colorbar.png";
output_final_img = "~/fig1.png";
coloredmesh.plot.colorbar.separate(cm, image.plot_extra_options = list('horizontal' = TRUE), png_options = list('filename'=output_cbar_img, 'width'=1800));
combine.colorbar.with.brainview.image(output_brain_img, output_cbar_img, output_final_img);You may have to play a bit with the resolution settings of your brain images and the colorbar to get this right (the background cropping makes it hard to compute the exact values in advance).
Yes, see the example notebook files in the directory web of the fsbrain repository. The Rmd files in that directory are actually notebooks in R markdown format.