FreeSurfer Installation

Introduction

FreeSurfer is a software suite used for the analysis and processing of neuroimaging data, particularly focusing on structural brain MRI scans. It’s an open-source software package developed by the Athinoula A. Martinos Center for Biomedical Imaging at Massachusetts General Hospital and Harvard Medical School.

FreeSurfer

This tool is primarily used for tasks such as cortical surface reconstruction, volumetric segmentation, subcortical structure analysis, and cortical thickness measurements. FreeSurfer employs a series of algorithms and processing steps to segment different brain structures, map the cortical surface, and provide quantitative information about brain anatomy.

It is widely utilized in neuroscience research, clinical studies, and medical imaging to study brain anatomy, examine changes in brain structures related to various neurological disorders, and analyze brain development.

The software operates through command-line tools and also provides a graphical user interface (GUI) called Freeview for visualization and manipulation of neuroimaging data. Its functionalities include the ability to generate 3D models of brain structures, visualize and analyze cortical thickness, surface area, and volume measurements, among other neuroimaging metrics.

FreeSurfer has contributed significantly to the understanding of brain structure and function and is commonly used in studies related to Alzheimer’s disease, schizophrenia, multiple sclerosis, and other neurological conditions.

Installation

1. Environment Installation
   caused by bad interpreter: No such file or directory

   sudo add-apt-repository universe
   sudo apt update
   sudo apt install csh tcsh

2. Download FreeSurfer
   https://surfer.nmr.mgh.harvard.edu/fswiki/rel7downloads

• freesurfer-linux-ubuntu20_amd64-7.4.0.tar.gz

3. Extract the file

4. Add the license file
   https://link.zhihu.com/?target=https%3A//surfer.nmr.mgh.harvard.edu/registration.html

Add the license.txt to your path.

5. Configurations

   $ cd ~/freesurfer
   $ export FREESURFER_HOME=/home/cluster/freesurfer
   $ source $FREESURFER_HOME/SetUpFreeSurfer.sh

6. Success

   -------- freesurfer-linux-ubuntu20_x86_64-7.4.0-20230510-e558e6e --------
   Setting up environment for FreeSurfer/FS-FAST (and FSL)
   FREESURFER_HOME   /home/cluster/freesurfer
   FSFAST_HOME       /home/cluster/freesurfer/fsfast
   FSF_OUTPUT_FORMAT nii.gz
   SUBJECTS_DIR      /home/cluster/freesurfer/subjects
   MNI_DIR           /home/cluster/freesurfer/mni

7. Check Version

       FreeSurfer is a set of tools for the analysis and visualization
   of structural and functional brain imaging data. FreeSurfer
   also refers to the structural imaging stream within the
   FreeSurfer suite.
   
   Users should consult the online documentation available at:
   
   http://surfer.nmr.mgh.harvard.edu
   
   Alternatively, the 'recon-all' command help-text provides
   adequate information to begin processing subject data, such
   as the sample subject 'bert' found in the 'freesurfer/subjects'
   directory.  Type 'recon-all --help' to view this help-text.
   
   Direct comments and questions to:
   
   freesurfer@nmr.mgh.harvard.edu
   
   You are running this version of FreeSurfer:
   
   freesurfer-linux-ubuntu20_x86_64-7.4.0-20230510-e558e6e

8. Test

   $ which freeview

   $ recon-all

   $ recon-all --help

   USAGE: recon-all
   
   Required Arguments:
   -subjid <subjid>
   -<process directive>
   
   Fully-Automated Directive:
   -all           : performs all stages of cortical reconstruction
   -autorecon-all : same as -all
   
   Manual-Intervention Workflow Directives:
   -autorecon1    : process stages 1-5 (see below)
   -autorecon2    : process stages 6-23
                   after autorecon2, check white surfaces:
                       a. if wm edit was required, then run -autorecon2-wm
                       b. if control points added, then run -autorecon2-cp
                       c. proceed to run -autorecon3
   -autorecon2-cp : process stages 12-23 (uses -f w/ mri_normalize, -keep w/ mri_seg)
   -autorecon2-wm : process stages 15-23
   -autorecon2-inflate1 : 6-18
   -autorecon2-perhemi : tess, sm1, inf1, q, fix, sm2, inf2, finalsurf, ribbon
   -autorecon3    : process stages 24-34
                       if edits made to correct pial, then run -autorecon-pial
   -hemi ?h       : just do lh or rh (default is to do both)
   
   Autorecon Processing Stages (see -autorecon# flags above):
       1.  Motion Correction and Conform
       2.  NU (Non-Uniform intensity normalization)
       3.  Talairach transform computation
       4.  Intensity Normalization 1
       5.  Skull Strip
   
       6.  EM Register (linear volumetric registration)
       7.  CA Intensity Normalization
       8.  CA Non-linear Volumetric Registration 
       9.  Remove neck
       10. EM Register, with skull
       11. CA Label (Aseg: Volumetric Labeling) and Statistics
   
       12. Intensity Normalization 2 (start here for control points)
       13. White matter segmentation
       14. Edit WM With ASeg
       15. Fill (start here for wm edits)
       16. Tessellation (begins per-hemisphere operations)
       17. Smooth1
       18. Inflate1
       19. QSphere
       20. Automatic Topology Fixer
       21. White Surfs (start here for brain edits for pial surf)
       22. Smooth2
       23. Inflate2
   
       24. Spherical Mapping
       25. Spherical Registration 
       26. Spherical Registration, Contralater hemisphere
       27. Map average curvature to subject
       28. Cortical Parcellation (Labeling)
       29. Cortical Parcellation Statistics
       30. Pial Surfs
       31. WM/GM Contrast
       32. Cortical Ribbon Mask
       33. Cortical Parcellation mapped to ASeg
       34  Brodmann and exvio EC labels
   
   Step-wise Directives
   See -help
   
   Expert Preferences
   -pons-crs C R S : col, row, slice of seed point for pons, used in fill
   -cc-crs C R S : col, row, slice of seed point for corpus callosum, used in fill
   -lh-crs C R S : col, row, slice of seed point for left hemisphere, used in fill
   -rh-crs C R S : col, row, slice of seed point for right hemisphere, used in fill
   -nofill        : do not use the automatic subcort seg to fill
   -watershed cmd : control skull stripping/watershed program
   -xmask file : custom external brain mask to replace automated skullstripping
   -wsless : decrease watershed threshold (leaves less skull, but can strip more brain)
   -wsmore : increase watershed threshold (leaves more skull, but can strip less brain)
   -wsatlas : use atlas when skull stripping
   -no-wsatlas : do not use atlas when skull stripping
   -no-wsgcaatlas : do not use GCA atlas when skull stripping
   -wsthresh pct : explicity set watershed threshold
   -wsseed C R S : identify an index (C, R, S) point in the skull
   -norm3diters niters : number of 3d iterations for mri_normalize
   -normmaxgrad maxgrad : max grad (-g) for mri_normalize. Default is 1.
   -norm1-b N : in the _first_ usage of mri_normalize, use control 
               point with intensity N below target (default=10.0) 
   -norm2-b N : in the _second_ usage of mri_normalize, use control 
               point with intensity N below target (default=10.0) 
   -norm1-n N : in the _first_ usage of mri_normalize, do N number 
               of iterations
   -norm2-n N : in the _second_ usage of mri_normalize, do N number 
               of iterations
   -cm           : conform volumes to the min voxel size 
   -no-fix-with-ga : do not use genetic algorithm when fixing topology
   -fix-diag-only  : topology fixer runs until ?h.defect_labels files
                       are created, then stops
   -seg-wlo wlo : set wlo value for mri_segment and mris_make_surfaces
   -seg-ghi ghi : set ghi value for mri_segment and mris_make_surfaces
   -nothicken   : pass '-thicken 0' to mri_segment
   -no-ca-align-after : turn off -align-after with mri_ca_register
   -no-ca-align : turn off -align with mri_ca_label
   -deface      : deface subject, written to orig_defaced.mgz
   
   -expert file     : read-in expert options file
   -xopts-use       : use pre-existing expert options file
   -xopts-clean     : delete pre-existing expert options file
   -xopts-overwrite : overwrite pre-existing expert options file
   -termscript script : run script before exiting (multiple -termscript flags possible)
   This can be good for running custom post-processing after recon-all
   The script must be in your path. The subjid is passed as the only argument
   The current directory is changed to SUBJECTS_DIR before the script is run
   The script should exit with 0 unless there is an error
   
   -mprage : assume scan parameters are MGH MP-RAGE protocol
   -washu_mprage : assume scan parameters are Wash.U. MP-RAGE protocol.
                   both mprage flags affect mri_normalize and mri_segment,
                   and assumes a darker gm.
   -schwartzya3t-atlas : for tal reg, use special young adult 3T atlas
   
   -threads num  : set number of threads to use
   
   Notification Files (Optional)
   -waitfor file : wait for file to appear before beginning
   -notify  file : create this file after finishing
   
   Status and Log files (Optional)
   -log     file : default is scripts/recon-all.log
   -status  file : default is scripts/recon-all-status.log
   -noappend     : start new log and status files instead of appending
   -no-isrunning : do not check whether this subject is currently being processed
   
   Segmentation of substructures of hippocampus and brainstem 
   (These deprecated; please see segmentHA_T1.sh, segmentHA_T1.sh, segmentHA_T1_long.sh, segmentBS.sh)
   -hippocampal-subfields-T1 : segmentation of hippocampal subfields using input T1 scan
   -hippocampal-subfields-T2 file ID : segmentation using an additional scan (given by file);
                                       ID is a user-defined identifier for the analysis
   -hippocampal-subfields-T1T2 file ID : segmentation using additional scan (given by file) and input T1
                                           simultaneously; ID is a user-defined identifier for the analysis
   -brainstem-structures : segmentation of brainstem structures
   
   Other Arguments (Optional)
   -sd subjectsdir : specify subjects dir (default env SUBJECTS_DIR)
   -mail username  : mail user when done
   -umask umask    : set unix file permission mask (default 002)
   -grp groupid    : check that current group is alpha groupid 
   -onlyversions   : print version of each binary and exit
   -debug          : print out lots of info
   -allowcoredump  : set coredump limit to unlimited
   -dontrun        : do everything but execute each command
   -version        : print version of this script and exit
   -help           : voluminous bits of wisdom

freeview

Qt Installation

sudo apt-get install qt5-default 

View the console

freeview

Download tutorial_data

https://surfer.nmr.mgh.harvard.edu/pub/data/tutorial_data.tar.gz

Introduction to Freesurfer Output

export TUTORIAL_DATA=/home/cluster/freesurfer/tutorial_data
export SUBJECTS_DIR=$TUTORIAL_DATA/buckner_data/tutorial_subjs
cd $SUBJECTS_DIR

freeview -v \
good_output/mri/T1.mgz \
good_output/mri/wm.mgz \
good_output/mri/brainmask.mgz \
good_output/mri/aseg.mgz:colormap=lut:opacity=0.2 \
-f good_output/surf/lh.white:edgecolor=blue \
good_output/surf/lh.pial:edgecolor=red \
good_output/surf/rh.white:edgecolor=blue \
good_output/surf/rh.pial:edgecolor=red

Reference

1. FreeSurfer Version 7 Release
   https://surfer.nmr.mgh.harvard.edu/fswiki/rel7downloads

2. freesurfer7.2.0安装在Ubuntu 21.04
   https://zhuanlan.zhihu.com/p/538412463

3. Unable to locate package csh or tcsh [closed]
   https://stackoverflow.com/questions/66954590/unable-to-locate-package-csh-or-tcsh

4. FreeSurfer Tutorial
   https://andysbrainbook.readthedocs.io/en/latest/FreeSurfer/FreeSurfer_Introduction.html

5. stackoverflow - QT plarform error
   https://stackoverflow.com/questions/60042568/this-application-failed-to-start-because-no-qt-platform-plugin-could-be-initiali

6. stackoverflow - Unable to locate package csh or tcsh
   https://stackoverflow.com/questions/66954590/unable-to-locate-package-csh-or-tcsh