Freesurfer
Overview
FreeSurfer is a software package developed at the Athinoula A. Martinos Center for Biomedical Imaging in Massachusetts, USA. It consists of a set of automated tools/functions for the analysis and visualisation of structural and functional brain imaging data.
Versions 7.3.2, 7.2.0, 7.1.1, 7.1.0, 6.0.0 are installed along with 5.3.0-HCP which contains a slightly different version of the mris_make_surfaces program than is part of the standard FreeSurfer 5.3.0 release for the Human Connectome Project.
Restrictions on use
This software requires that users are added to a unix group to access it. Requests for access should be directed to its-ri-team@manchester.ac.uk.
All users MUST read and agree to the freesurfer license before they can be added to the unix group. The information below provides some guidance, but is not a substitute for the license:
What may freesurfer be used for?
You may use freesurfer only for academic research purposes.
What may freesurfer not be used for?
You must not use freesurfer for clincal work or commercial purposes.
How should the program be cited?
If you include the results from freesurfer in a publication you must include an appropriate citation based on the information available on the Freesurfer Citation webpage.
You are not permitted to use freesurfer logos and associated trademarks.
Export regulations including remote access
You must comply with all United States and United Kingdom export control laws and regulations controlling the export of the software, including, without limitation, all Export Administration Regulations of the United States Department of Commerce. Among other things, these laws and regulations prohibit, or require a license for, the export of certain types of software to specified countries.
Please be aware that allowing remote access from outside the United Kingdom may constitute an export.
Modifications and contributions to freesurfer
Modifications, bug fixes, and contributions may constitute University intellectual property. You should not undertake modifications, bug fixes or contribution without first seeking guidance about licensing said intellectual property.
The submission of data is classed as a contribution and as such is discouraged by the University. If you choose to contribute data it needs to be anonymised and fall outside the scope of the Data Protection Act 1998.
Risks
The freesurfer license is quite permissive. You are required to discuss anything that is unclear about your usage and the license with your line management in the first instance to obtain further guidance.
Set up procedure
To access the software please load one of the following modulefiles for the version you wish to use:
module load apps/binapps/freesurfer/7.4.1 # Includes the MATLAB (R2019b) runtime module load apps/binapps/freesurfer/7.3.2 # Includes the MATLAB (R2019b) runtime module load apps/binapps/freesurfer/7.2.0 # Includes the MATLAB (R2014b) runtime module load apps/binapps/freesurfer/7.1.1 # Includes the MATLAB (R2014b) runtime module load apps/binapps/freesurfer/7.1.0 # Includes the MATLAB (R2014b) runtime module load apps/binapps/freesurfer/6.0.0 module load apps/binapps/freesurfer/5.3.0-HCP
The FreeSurfer installation on the CSF expects a directory called “subjects” to exist on the user’s scratch space. This must be
created if it doesn’t already exist, using the following commands:
mkdir ~/scratch/subjects
| Please note that the scratch tidy policy is in force and so any files older than 3 months in your scratch area will be deleted automatically by the system. You should ensure all results that you want to keep are copied to your CSF home directory or additional Research Data Storage that your group or project might have access to. |
Running the application
FreeSurfer’s recon-all function will fully automatically take a high-resolution T1-weighted MRI image volume of the brain, strip the skull, scalp and eyes, segment the white and grey matter and cerebrospinal fluid, and parcellate the cerebral cortex and sub-cortical tissues into neuro-anatomically distinct regions. recon-all is fully documented at http://www.freesurfer.net/fswiki/recon-all and http://www.freesurfer.net/fswiki/ReconAllTableStableV5.1.
How to run recon-all on a dataset on the CSF3
FreeSurfer predefines the full path for the “subjects” directory as $SUBJECTS_DIR (an environment variable set by the modulefile.) A sub-directory must be created in the $SUBJECTS_DIR directory for each subject dataset that FreeSurfer will be run on. The name of a subject’s sub-directory should be unique and easily identifiable (their “subjid“). Within a subject’s sub-directory a folder named mri must be created, and within this a sub-folder called orig must be created. The following command line is an example of doing this in one command:
# Note: $SUBJECTS_DIR is automatically set by the modulefile to be ~/scratch/subjects/
mkdir -p $SUBJECTS_DIR/subjid/mri/orig
#
# Change this to a subject's unique id
A high-resolution (voxel size of 1x1x1 mm or less) T1-weighted MRI image volume (at least) of the brain must be copied into the
$SUBJECTS_DIR/subjid/mri/orig for each subject. FreeSurfer requires input images to be in MGZ format and have a 3-digit zero-padded number as the filename. Use FreeSurfer’s mri_convert (documentation for this at http://www.freesurfer.net/fswiki/mri_convert) to convert an image to MGZ from any other supported format (e.g. a 3D volume in Analyze format
called “T1brain”), with a command line such as:
mri_convert -it analyze -ot mgz $SUBJECTS_DIR/subjid/mri/orig/T1brain $SUBJECTS_DIR/subjid/mri/orig/001.mgz
# #
###Change to the required subject id###
recon-all can now be run on the dataset. All runs must be submitted to the batch system, SGE. An example job submission script:
#!/bin/bash --login #$ -cwd # chose the version you require module load apps/binapps/freesurfer/6.0.0 recon-all -s bert -all
Which is then submitted using the command:
qsub scriptname
FreeSurfer only runs on a single core, it cannot be run on multiple cores.
It takes approximately 48 hours to complete on a single subject dataset. The results all appear in the folders and subfolders in $SUBJECTS_DIR/subjid, with the image volumes (the segmentation and parcellation volumes) in $SUBJECTS_DIR/subjid/mri. FreeSurfer will output all image volumes in MGZ format. The mri_convert function can be used to convert the required image volumes to the preferred format for the user’s use.
Visualisation
Freesurfer includes a visualisation tool called freeview.
To run this you should use qrsh.
qrsh -l short # Wait to be logged in to a compute node, then: module load apps/binapps/freesurfer/6.0.0 # Choose the version you require freesurfer -v /path/to/T1.mgz # To return to the login node: exit
Mac users should ensure that Xquartz is installed and “ssh -Y” to csf3 in order to activate the display.
To run Freesurfer and freeview, you should:
qrsh -l short module load libs/gcc/glx/1.5 module load apps/binapps/freesurfer/7.2.0 freeview #Then, you can load your data file for visualisation