Freesurfer

FreeSurfer is a software package for the analysis and visualization of structural neuroimaging data.

It is developed by the Laboratory for Computational Neuroimaging at the Martinos Center for Biomedical Imaging.

FreeSurfer provides full processing streams for structural and functional MRI and includes tools for linear and nonlinear registration, cortical and subcortical segmentation, cortical surface reconstruction, statistical analysis of group morphometry, diffusion MRI, PET analysis, and much more. It is also the structural MRI analysis software of choice for the Human Connectome Project.

For expansive documentation on using and understanding FreeSurfer tools, please visit the FS Wiki.

Running the recon-all command

Recon-all (recon = reconstruction) is a command that takes an anatomical dataset (T1-weighted image) and performs many common preprocessing steps on it, with the goal of converting the 3D brain image (.nii or .dcm) into a 2D surface. It is helpful to imagine the reconstruction as taking a crumpled balloon (T1w) and blowing it up (inflated surface). This inflated surface is particularly helpful when analyzing regions of the cortex where some voxels may contain signal from two separate gyri. However, it is also helpful when analyzing signal found in the sulci.

To run recon-all on Oscar:

module load freesurfer/8.0.0
recon-all -i t1w.nii.gz -s <subject_name> -sd <path_to_your_folder> -all 

The -i flag points to the T1-weighted anatomical file. If you are running recon-all from the directory containing that file, you can simply put the file name. Otherwise, you must include the full path.

-s describes the subject name, which will be attached to the output files. This can be anything.

-sd points to the subjects directory, where all output will be stored. This is a particularly important option to include when using Oscar, since the default subjects directory is within the Freesurfer module and lacks write privileges. With this flag, you can create your own output directory and it will be named what you specified with the -s flag.

-alltells recon-all to perform all preprocessing steps. For the full list of steps, please refer to Freesurfer's documentation found here: https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all.

The most recent version of Freesurfer on Oscar, freesurfer/8.0.0, requires python3 and takes approximately 2.5 hours to complete. The previous version, freesurfer/7.3.2, is still available and takes 6-8 hours.

These are the output directories you will see, located in the specified -sd path:

Output directories of recon-all.

label contains text files which hold spatial information on different regions of the brain, along with those regions' atlas annotations.

mri contains many different brain volumes with various levels of preprocessing. Importantly, this is where volumes such as the skull-stripped brain, the subcortical segmentations of the brain, and the brain mask are saved.

scripts contains the log files for the recon-all command. Notably, recon-all.log is where a full history of the workflow can be found.

stats contains files with information on the thickness and volume for each segmentation and cortical parcellation.

surf contains the recon-all generated brain surfaces. This is where both the inflated and non-inflated surfaces are stored.

touch contains files which are created each time a step of recon-all step is executed. These are used by Freesurfer to determine where to begin if the script is paused and restarted.

The temporary directory (tmp) and trash should both be empty at the end of processing.

Output from recon-all can be viewed with Freesurfer's image viewer (freeview). To view a surface from the surf directory, use the -f flag followed by the file name. To view a volume from the mri directory, use the -v flag. Volume files have the .mgh or .mgz extension, which are unique to Freesurfer and stand for Massachusetts General Hospital, and Massachusetts General Zipped, respectively.

freeview -f lh.pial rh.pial 

If you are using freesurfer/8.0.0 and are having issues opening the freeview GUI, try checking whether or not you have the anaconda module loaded. If you do, unload it and try again.

The left and right pial surfaces viewed using freeview.

freeview -f lh.inflated rh.inflated 

The left and right inflated brain surfaces viewed using freeview. In this image, red represents the sulci and green represents the gyri.

Segmentation and Parcellation

Included in recon-all's workflow is segmentation of the subcortical white and grey matter structures (hippocampus, amygdala, caudate, putamen, thalamus, etc) and parcellation of the cortex. Parcellation is conducted with respect to two different atlases, the Desikan-Killiany atlas (/mri/aparc.DKTatlas+aseg.mgz) and the Destrieux atlas (/mri/aparc.a2009s+aseg.mgz). The main difference between the two is that the Destrieux atlas contains more parcellations and is used in more fine-tuned analyses.

freeview -v orig.mgz aparc.a2009s+aseg.mgz

T1w image with the Destrieux Atlas segmentation/parcellation overlayed.

Volumes/surfaces can also be opened within the freeview window via the file tab.

The tutorial below is helpful in becoming more familiar with the output of recon-all:

FsTutorial/OutputData_freeview - Free Surfer Wiki