In neuroconductor/ggsegExtra: Extra Utilities for the 'ggseg'-Plotting Tool

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

New ggseg3d-atlases can be obtained by converting surfaces into tridimensional meshes in .ply format. The pipeline for creating cortical surfaces and volumetric images into ggseg3d-atlases is slightly different than for ggseg-atlases.

One has to convert the images with information on your labels to a Freesurfer annotation file (cortical) or to a .mgz file (subcortical), and then run an R-function calling Freesurfer and FSL to create the ggseg3d-atlas.

The conversion is based on the scripts available in https://github.com/andersonwinkler/areal by Anderson Winkler. Essentially, the functions are identical to A. Winkler's work, with small edits to better adapt to the R and the specific purpose of ggseg3d-atlas creation. All credit goes to Anderson Winkler for making these pipelines, see more information on his webpage.

Prerequisites

These functions will not work on Windows systems, as Freesurfer is not available for Windows. If you desperately need to use it on Windows-bases systems, you can look into Freesurfer docker containers and see if you can connect that to R, but we have not tried this. Finally one has to have R and the ggseg-family of packages to convert the .ply meshes into a ggseg3d-atlas.

From a surface image.

1) Make annotation file (bash + Freesurfer)

Atlases already available in Freesurfer have annotation files, making this step unnecessary. These can be found in the Freesufer subject directory, within a subject in the label/ folder, look for files ending with .annot. For other files (like results from your vertex-vise analyses etc), you will need to convert the ROIs you have to annotation files. This may require any of the following conversions:

Convert overlay files into annotations. (e.g. overlay results to annotations)
Downsample annotation files (e.g.from fsaverage to fsaverage5)
Register files across different subject templates (from 164k_FS_LR [HCP] to fsaverage 5).
- The specific procedure will depend on your original image
- FreeSurfer's mri_surf2annot, mri_surf2surf, mri_label2annot or mri_surfcluster, should be capable to do most of the required conversions

2) Run `make_aparc_2_3datlas()`(R)

This script converts your annotations (.annot) into tridimensional (.ply) meshes, and then to a ggseg3d-atlas. Without any arguments, it will create the aparc (Desikan-Killany atlas), based on annotation files in the Freesurfer subejcts directory.

# Desikan-Killany atlas (a.k.a aparc)
dt <- make_aparc_2_3datlas()

# Desterieux atlas
dt <- make_aparc_2_3datlas(annot = "aparc.a2009s")

# Yeo 7 networks atlas
dt <- make_aparc_2_3datlas(annot = "Yeo2011_7Networks_N1000")

Depending on the set-up you have, where you are storing data, etc. you have many arguments to the function to choose from. The arguments for the function are:

annot : annotation base name, "aparc" default
subject : Freesufer subject, "fsaverage5" default
hemisphere : hemisphere(s), c("rh", "lh") default
surface : surfaces to create atlas from, c("inflated", "LCBC", "white") default
subjects_dir : path to Freesurfer $SUBJECTS_DIR, freesurfer::fs_subj_dir() default
annot_dir : directory where the annot files are, file.path(subjects_dir, subject, "label") default
output_dir : output directory for intermediary files, tempdir() default
cleanup : logical if output directory intermediary files should be deleted at completion, TRUE default
verbose : logical to be verbose or not, TRUE (default)

Depending on what you need to do, and which folders you may have write-access for on your system, any of these might need changing. You can use any surface already existing in the subjects surf folder. If you have made your own custom annotation file, and placed it on the Desktop, with the names "lh.myResults.annot" and "rh.myResults.annot", you can use this file doing:

# myResults atlas
dt <- make_aparc_2_3datlas(annot = "myResults", 
                       annot_dir = "~/Desktop")

Note that the "LCBC" surface only works for subject "fsaverage5", if you want any other subject, you will need to convert it with freesurfer::mri_surf2srf(). If you want to make your own specialized surface, you can, but you should look into Freesurfer documentation to do that.

You will notice that the atlas column taked directly the name of the annot file, and that the region and label columns are the same. If you are in the process of making an atlas contribution, there are a couple steps necessary for the atlas to be included.

1) atlas-name should be short and easily recognisable
2) the atlas column should have the same name as the atlas object it self
3) contents in the region column should be cleaned to have proper names, not the label names. This is to make it nicer when plotting and make the regions more human readable. Please take care in this step.

From a volume image

1) Create volumetric image (bash + Freesurfer / FSL)

The image needs to have the following characteristics:

1) Be in MNI305; 2mm FreeSurfer space
2) Consists of integer values, in which each integer reflects a different ROI
- One will have to perform basic transformations (mostly thresholding, binarizing and, registration) with neuroimaging software tools like Freesurfer and FSL. - The specific process will depend on the initial information, but one should manage to convert the data using the following functions: fslmaths (FSL) and mri_convert, mri_vol2vol, mris_calc (FreeSurfer). - The resulting template file must be in Freesurfer.mgz format.

2) Run `make_aseg_2_3datlas()` (R)

This script converts your template images (.mgz) into tridimensional (.ply) meshes, and then to a ggseg3d-atlas. Without any arguments, it will create the aseg atlas, based on mri/aseg.mgz file in the Freesurfer subjects directory, together with the "ASegStatsLUT.txt" file from the Freesurfer main directory.

# aseg atlas (a.k.a aseg)
dt <- make_aseg_2_3datlas()

Depending on the set-up you have, where you are storing data, etc. you have many arguments to the function to choose from. The arguments for the function are:

template : path to the template.mgz file
color_lut : path to color LUT, or a data.frame with color LUT (ctab) properties
steps : there are 5 steps in the transformation, if partial transformation has been done before, and there has been no cleanup, then you can skip the steps already run.
subject : Freesufer subject, "fsaverage5" default
subjects_dir : path to Freesurfer $SUBJECTS_DIR, freesurfer::fs_subj_dir() default
output_dir : output directory for intermediary files, tempdir() default
cleanup : logical if output directory intermediary files should be deleted at completion, TRUE default
verbose : logical to be verbose or not, TRUE (default)

Depending on what you need to do, and which folders you may have write-access for on your system, any of these might need changing. You will need to make sure you have a template.mgz file made in 1) before you can run this.

# myResults template without a color LUT
dt <- make_aparc_2_3datlas(template = "path/to/myResults.mgz", 
                       color_lut = NULL)

# myResults template with a color LUT
dt <- make_aparc_2_3datlas(template = "path/to/myResults.mgz", 
                       color_lut = "path/to/myResults_LUT.txt")