In neuroconductor/ggseg: Plotting Tool for Brain Atlases

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

devtools::load_all(".")
subject_dir <- here::here("tests/testthat/data/")

stats_file <- paste0(subject_dir, "bert/stats/lh.aparc.stats")

Freesurfer already have files that are compatible with ggseg in some extent. There are naming conventions and file-formats that are different, and as such it can at times be a little tricky to get data directly from Freesurfer into R, and subsequently plotting in ggseg.

Raw stats files

Read in single raw stats file

If recon-all from Freesurfer has been run, each participant should have a stats folder, with various parcellation data and summary statistics for those parcellations and measures. These have many header lines before the data acutally start, and can have some formatting difficult to handle in R.

The function read_freesurfer_stats is made to easily read in raw stats tables from each individual, without needing to go through Freesurfers internal converters. When using this file, remembering which hemisphere is read in is important, as this information must be added to the label column for ggseg to recognise the region labels.

library(ggseg)
library(ggplot2)

subjects_dir <- "/Applications/freesurfer/subjects/"

library(ggseg)
library(ggplot2)

subjects_dir <- here::here("tests/testthat/data")

stats_file <- file.path(subjects_dir, "bert/stats/lh.aparc.stats")
data <- read_freesurfer_stats(stats_file)
data

This data should be well-suited for use with ggseg.

data %>% 
  mutate(label = paste0("lh_", label)) %>% 
  ggseg(atlas = dk, mapping = aes(fill = ThickAvg))

Read in raw stats files for an atlas for all subjects

A convenience function also exists for those wanting to circumvent the aparcstats2table and asegstats2table from freesurfer for creating larger datasets of all subjects for a specific parcellation and metric. Using the function read_freesurfer_stats, read_atlas_files uses regular expression for the atlas you want to extract data from, and grabs this data from all available subjects. Be careful with your pattern matching to be sure you get exactly the atlas you want. For instance, there are several atlases with with string aparc in them. So in order to get only the default aparc stats, we need to specify aparc.stats$, which will only read those files ending with that particular string. This function can throw warnings, which is most cases can be ignored.

dat <- read_atlas_files(subject_dir, "aparc.stats$")
dat

Since all files are read in, the hemisphere in the label is already fixed, so it is easy to plot.

ggseg(dat, mapping = aes(fill = ThickStd))

With this data, we can even have a look at all the metrics at once.

library(dplyr)
library(tidyr)

dat %>% 
  gather(stat, val, -subject, -label) %>% 
  group_by(stat) %>% 
  ggseg(mapping = aes(fill = val)) +
  facet_wrap(~stat)

Freesurfer stats tables

Freesurfer has internal functions to convert their raw stats files into tables, gather subject into a single data file with particular metric. It is quite common to use these files, but again the formatting is not something R is very happy with. The function read_freesurfer_table() is for easier import of these files, particularly for further plotting with ggseg.

# Path to our particular file, yours will be wherever you have saved it
table_path <- here::here("tests/testthat/data/aparc.volume.table")
table_path

read_freesurfer_table(table_path)

The file is read and has three columns only. The subject column, the label column, and a column with the values of the metric. Since the stats tables can contain different measures, and these are handled somewhat differently, we for convenience leave the default reading of the table this way. To work with ggseg, though, the labels usually (but not always) need a little cleaning. In this case we read in a volume table, and as such all labels end with "volume". ggseg will _not recognise this matching the atlas, and will therefore not plot.

Easiest way to clean, is by using the measure argument for the function.

dat <- read_freesurfer_table(table_path, measure = "volume")
dat

This will do two things: 1) remove the label suffix, and 2) rename the value column to the measure supplied. Alternatively, you will need to do string manipulation on the label column your self, we recommend the stringr package in that case.

dat %>% 
  ggseg(mapping = aes(fill = volume))

An error will be thrown because the Freesurfer tables also include measures of total volume/region/thickness, estimated intracranial volume etc, which will not merge into the atlas, and the internal ggseg atlas-merging function throws a warning. To avoid this, you can remove those labels before plotting.

dat %>% 
  filter(grepl("lh|rh", label)) %>% 
  ggseg(mapping = aes(fill = volume))

neuroconductor/ggseg documentation built on May 15, 2021, 11:21 p.m.