| The CSF2 has been replaced by the CSF3 - please use that system! This documentation may be out of date. Please read the CSF3 documentation instead. To display this old CSF2 page click here. |
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 6.0.0, 5.3.0 & 5.0.0 are installed.
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 the module for the version you wish to use:
module load apps/binapps/freesurfer/6.0.0
module load apps/binapps/freesurfer/5.3.0
module load apps/binapps/freesurfer/5.0.0
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
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 CSF
FreeSurfer predefines the full path for the “subjects” directory as SUBJECTS_DIR. A subdirectory must be created in SUBJECTS_DIR for each subject dataset that FreeSurfer will be run on. The name of a subject’s subdirectory should be unique and easily identifiable (their subjid). Within a subject’s subdirectory a folder called “mri” must be created, and within this a subfolder called “orig” must be created. The following command line is an example of doing this:
mkdir -p $SUBJECTS_DIR/subjid/mri/orig
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
recon-all can now be run on the dataset. All runs must be submitted to the batch system, SGE. An example job submission script:
#SGE Stuff #$ -cwd #$ -V #$ -N recon_all_on_005 recon-all -subjid 005 -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.