Purpose of this post

I enjoy finding new ways to visualize data in a meaningful (and also aesthetically pleasing) way. Finding the right tools in order to get your message across adds value, but can be challenging. When I learned about this visualization toolbox with the multitude of options it has, I had to learn how to use it – and it’s actually quite simple!

The links to both the blog and GitHub pages below are extremely informative (so please also refer to them)! Here, I wanted to outline the installation process I used in order to get the program running in RStudio (Part 1) and provide some examples of things I have done with the toolbox to potentially spark some inspiration (Part 2)!

Getting Started

Source

All the credits for this awesome toolbox go to Dr. Athanasia Mowinckel & Dr. Didac Vidal Pineiro at the Center for Lifespan Changes in Brain and Cognition, University of Oslo. Be sure to check out Dr. Mowinckel’s blog, which has a great overview of the different options available with the toolbox.

ggseg GitHub link: https://github.com/LCBC-UiO/ggseg

ggseg GitHub README.md: https://github.com/LCBC-UiO/ggseg/blob/master/README.md

Note: There seem to be some updates happening at the moment with the toolbox, so this may not work 100% for you, but it worked for me in May of 2020. Updates to come if this changes.

Compatibility – what I used

Operating System: Windows 10

R version: 4.0.0

RStudio version: 1.2.5033

Installation Guide

Libraries to install prior to ggseg

library(ggplot2)
library(devtools)
library(tidyselect)
library(magrittr)
library(rmarkdown)
library(stringr)
library(stringi)
library(tibble)
library(dplyr)
library(purrr)
library(pandocfilters)
library(tidyr)

If some libraries are missing, use the command below with the toolbox name within the quotes as shown for tidyr.

$> install.packages("tidyr")

Installing ggseg

On the GitHub website, they state to use:

$> install.packages("remotes")
remotes::install_github("LCBC-UiO/ggseg", build_vignettes = TRUE)

Currently, there is a bug that is being fixed in the program with the Vignettes, so you will need to modify the code until this is fixed to:

$> install.packages("remotes")
$> remotes::install_github("LCBC-UiO/ggseg", build_vignettes = FALSE)

Personally, for me, I found that devtools works for installing the program without any problems. So since I already installed devtools above, just enter the following in RStudio:

$> devtools::install_github("LCBC-UiO/ggseg", build_vignettes = FALSE)
$> library(ggseg)

This will take a little bit of time and install version 1.5.4. You should see this in your window as:

$> building 'ggseg_1.5.4.tar.gz'

Atlases

After installing ggseg, there are two default atlases pre-installed based on the default Freesurfer output from running recon -all:

• Desikan-Killany cortical atlas (dk)
• Subcortical segmentation atlas (aseg)

Additionally, the following atlases are available and the links show examples for how to use the atlases. These are beyond the scope of this post. I will focus just on the default atlases included in the package.

• Yeo – both 7 and 17 network data
• Desterieux – the 2009 atlas
• Chen – both thickness and area maps
• Schaefer – both 17 and 7 networks
• Glasser – full atlas
• JHU – white tract atlas
• Tracula – white tract atlas
• ICBM – white tract atlas
• HO – Harvard-Oxford cortical (FSL)
• DefaultExtra – extra 2d view for dk, p/a division

To install the extra atlases, first install ggsegExtra:

$> devtools::install_github("LCBC-UiO/ggsegExtra", build_vignettes = FALSE)
$> library(ggsegExtra)

To check to see which atlases are available enter the following command:

$> ggseg_atlas_repos()

Install the atlas you would like to use with the format below (using the Glasser atlas as an example):

$> devtools::install_github("LCBC-UiO/ggsegGlasser")
$> library(ggsegGlasser)

Now you should hopefully have ggseg installed and ready to go without any problems!

Prerequisites

Before getting started, I first installed Ubuntu within Hyper-V on my Windows 10 computer following the instructions below:
https://www.hanselman.com/blog/UsingEnhancedModeUbuntu1804ForHyperVOnWindows10.aspx

Link to FreeSurfer installation page

While the link below is extremely well-written and helpful, I noticed a few steps during my installation process using Ubuntu for Hyper-V that required additional steps, not listed on the page. This is meant to help others using the same system that I am with the installation procedure – described in detail below. https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall

Installation Steps

1. Download Freesurfer

Download FreeSurfer for Linux from the download page while logged into your Ubuntu VM

File to download: freesurfer-Linux-centos6_x86_64-stable-pub-v6.0.0.tar.gz

Link to download (you may need to be logged into your Gmail account in order to download the file): https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/6.0.0/freesurfer-Linux-centos6_x86_64-stable-pub-v6.0.0.tar.gz

2. Change Permissions

You will need to make sure you have permissions to write into /usr/local/ which is where you will unpack the FreeSurfer package.

$> sudo chmod -R 777 /usr/local/   

3. Unpack FreeSurfer Package

Unpack the package making sure you are in the directory where you saved the package. For me this was:

$> cd /home/shaas/Downloads
$> tar -C /usr/local -xzvf freesurfer-Linux-centos6_x86_64-stable-pub-v6.0.0.tar.gz

4. Install additional necessary packages

$> sudo apt-get -y install bc binutils libgomp1 perl psmisc sudo tar tcsh unzip uuid-dev vim-common libjpeg62-dev 

5. Setup & Configuration

To begin using FreeSurfer, you need to open a terminal window and define and environment variable called FREESURFER_HOME which is set to the location FreeSurfer was installed, and then source the setup script. Sourcing FreeSurfer needs to be done every time you open a new terminal window. Or, you can add the two lines below to your default setup file (.bashrc or .cshrc) and FreeSurfer will be sourced automatically every time you open a new window.

## bash
$> export FREESURFER_HOME=/usr/local/freesurfer
$> source $FREESURFER_HOME/SetUpFreeSurfer.sh

If done correctly, you should see output similar to this:

Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME /usr/local/freesurfer
FSFAST_HOME     /usr/local/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii
SUBJECTS_DIR    /usr/local/freesurfer/subjects
MNI_DIR         /usr/local/freesurfer/mni

6. Get a license to use Freesurfer

A license key must be obtained to make the FreeSurfer tools operational. Obtaining a license is free and comes in the form of a license.txt file. Once you obtain the license.txt key file, copy it to your FreeSurfer installation directory. This is also the location defined by the FREESURFER_HOME environment variable.

Get license here: https://surfer.nmr.mgh.harvard.edu/registration.html

Once downloaded in Ubuntu, copy to folder where your FreeSurfer is:

$> cp /home/shaas/Downloads/license.txt /usr/local/freesurfer 

7. Additional items to install

$> sudo apt-get update
$> sudo apt-get upgrade
$> sudo apt-get install libtool autoconf build-essential pkg-config automake tcsh