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.

Checking the easybuild recipes

You can check the easybuild recipes for freesurfer online on GitHub or via a command line from any Compute Canada clusters:

{{Commands eb -S FreeSurfer CFGS1=/cvmfs/soft.computecanada.ca/easybuild/easyconfigs/f/FreeSurfer CFGS2=/cvmfs/soft.computecanada.ca/easybuild/ebfiles_repo/2017/FreeSurfer

* $CFGS1/FreeSurfer-5.3.0-centos4_x86_64.eb
* $CFGS1/FreeSurfer-5.3.0-centos6_x86_64.eb
* $CFGS1/FreeSurfer-5.3.0-matlab-2013.patch
* $CFGS1/FreeSurfer-6.0.0-centos6_x86_64.eb
* $CFGS1/FreeSurfer-6.0.1-centos6_x86_64.eb
* $CFGS1/FreeSurfer-7.1.0-centos6_x86_64.eb
* $CFGS1/FreeSurfer-7.1.0-centos7_x86_64.eb
* $CFGS2/FreeSurfer-5.3.0-centos4_x86_64.eb
* $CFGS2/FreeSurfer-5.3.0-centos6_x86_64.eb
* $CFGS2/FreeSurfer-5.3.0-matlab-2013.patch
* $CFGS2/FreeSurfer-6.0.0-centos6_x86_64.eb

}}

Installation in your Home with Easybuild

The following procedure will install FreeSurfer 6.0.0 in your home directory in /home/$USER/.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 --disable-enforce-checksums
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

[name@server ~]$ module load freesurfer/6.0.0
[name@server ~]$ cd $FREESURFER_HOME

Use nano or any other text editor of your choice and create a file /home/$USER/.license and add the license text (example):

name.name@university.ca
12345
*A1BCdEfGHiJK
ABCd0EFgHijKl

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.

Installation in a shared folder

Using EasyBuild, it is possible to install the program in a shared location (like project) and make the code available for any other member of the group. The following will install freesurfer under the project def-someuser and the module under the user's directory /home/$USER/.local/easybuild/modules/2017.

The instructions are:

newgrp def-someuser
installdir=/home/$USER/projects/def-someuser/$USER
moduledir=/home/$USER/.local/easybuild/modules/2017
pathtosrc=/home/$USER/software
eb FreeSurfer-6.0.1-centos6_x86_64.eb --installpath-modules=${moduledir} --prefix=${installdir} --sourcepath=${pathtosrc}

If it complains about checksums, add the option --disable-enforce-checksums to the eb command.

To make the program accessible for all members of the group, two more steps are required:

• You need to give all members of your group read and exec access to the installation directory /home/$USER/projects/def-someuser/$USER,. To see how to give them access to this directory, please visit the data sharing page.
• Each member of the group will need to put the module file in their own home directories. The module file is within the directory:

/home/$USER/.local/easybuild/software/2017/Core/freesurfer/6.0.1.lua</code>

Each member of the group will need to create the directory /home/$USER/.local/easybuild/software/2017/Core/freesurfer and put the file 6.0.1.lua:

[name@server ~]$ mkdir -p /home/$USER/.local/easybuild/software/2017/Core/freesurfer
[name@server ~]$ cp 6.0.1.lua /home/$USER/.local/easybuild/software/2017/Core/freesurfer

The above will set the module (only the module file that points to the installation directory under project) in their own directory.

The module can be loaded from their own accounts using:

[name@server ~]$ module load freesurfer/6.0.1
[name@server ~]$ cd $FREESURFER_HOME

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

File : mysub.sh

#!/bin/bash

#SBATCH --account=def-someuser
#SBATCH --mem=16G
#SBATCH --time=10:00:00

# Load the module:

module load freesurfer/6.0.0

# set the variables:

export SUBJECTS_DIR=<User_Defined_DIR>
source $EBROOTFREESURFER/FreeSurferEnv.sh

echo "Starting run at: `date`"

recon-all command

echo "Program finished with exit code $? at: `date`"

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