FreeSurfer

This article is a draft

This is not a complete article: This is a draft, a work in progress that is intended to be published into an article, which may or may not be ready for inclusion in the main wiki. It should not necessarily be considered factual or authoritative.

Introduction

FreeSurfer is a set of tools for analysis and visualization of structural and functional brain imaging data. FreeSurfer contains a fully automatic structural imaging stream for processing cross sectional and longitudinal data.

FreeSurfer 5.3 as a global module

In the Compute Canada software stack, you may load the freesurfer/5.3.0 module.

FreeSurfer come up with a script FreeSurferEnv.sh that should be sourced to setup correctly the environment variables such as PATH and PERL5LIB:

source $EBROOTFREESURFER/FreeSurferEnv.sh

FreeSurfer 6.0 and newer versions

Due to a change in the license terms, we now longer install the code as a central module. If needed, please install it in your home directory or in your project space with EasyBuild.

Download the software

Select a version (6.0.0 or newer) in the download repository, and download the corresponding freesurfer-Linux*vX.Y.Z.tar.gz archive on your favorite cluster.

Installation in your Home with Easybuild

The following procedure will install FreeSurfer 6.0.0 in your home directory in .local/easybuild/software/2017/Core/freesurfer/6.0.0/.

1. Go to the folder that contains the freesurfer-Linux-centos6_x86_64-stable-pub-v6.0.0.tar.gz archive
2. Unload all modules: module purge
3. Install with Easybuild: eb FreeSurfer-6.0.0-centos6_x86_64.eb
4. register for the FreeSurfer license key [1]
5. Your user license will have to go in: $HOME/.local/easybuild/software/2017/Core/freesurfer/6.0.0/.license

module load freesurfer/6.0.0 cd $FREESURFER_HOME nano .license

add the license text (example):

   name.name@university.ca
   12345
   *A1BCdEfGHiJK
   ABCd0EFgHijKl

type CTRL+x, y, enter

To load the private module: module load freesurfer/6.0.0

When this page was created, Compute Canada was supporting up to version 6.0.1. You can check for newer versions here.

Hippocampus and brainstem processing

To perform processing of the hippocampus and brainstem, download and install matlab runtime 2012b from the freesurfer website:

   module load freesurfer/6.0.0
   cd $FREESURFER_HOME
   
   curl "http://surfer.nmr.mgh.harvard.edu/fswiki/MatlabRuntime? 
   action=AttachFile&do=get&target=runtime2012bLinux.tar.gz" -o "matlab_runtime2012bLinux.tar.gz"
   
   tar xvf matlab_runtime2012bLinux.tar.gz 

Example of working batch script for freesurfer version >= 6.0.0

    #!/bin/sh
    #SBATCH --account=def-user
    #SBATCH --mail-type=FAIL
    #SBATCH --mem=16G
    #SBATCH --time=10:00:00
    #SBATCH --output=outputfile
    
    module load freesurfer/6.0.0
    export SUBJECTS_DIR=User_Defined_DIR
    source $EBROOTFREESURFER/FreeSurferEnv.sh
    
    recon-all command

Examples of required walltimes

• recon-all -all :

#SBATCH --time=08:00:00

• recon-all -qcache :

#SBATCH --time=00:20:00

• recon-all -base -tp1 -tp2 :

#SBATCH --time=10:00:00

• recon-all -long subjid -base base :

#SBATCH --time=10:00:00

• recon-all -hippocampal-subfields-T1 :

#SBATCH --time=00:40:00

• recon-all -brainstem-structures:

#SBATCH --time=00:30:00

Installation in a shared folder

It is possible to move installed files (with Easybuild) to the project space, but permissions have to be fixed.

• Recursively set the proper group ID of the freesurfer directory
• Move the data to the desired location in the project space
• Copy the module file to a shared location, and edit all paths in the module file.