Skip to content

FreeSurfer

This page summarises how to use FreeSurfer on the OxCIN FMRIB OOD Remote Desktop system and SLURM cluster, how to load the available versions, and how to set up the required Freesurfer licence file.

Availability on the cluster

FreeSurfer is available on the OOD cluster through Environment Modules.

To see which versions are installed:

module spider freesurfer

To load a version for the current shell:

module add freesurfer

Or load a specific version if you need one:

module add freesurfer/<version>

Licence file setup

FreeSurfer requires a licence file before it will run. Register for a licence at the official FreeSurfer site:

Once you have the licence file, place it in your home directory as .freesurfer-license, then run:

module add freesurfer-license
freesurfer-license ~/.freesurfer-license

Version-specific notes

FreeSurfer 8.1

FreeSurfer 8.1 is provided in several different configurations:

  • freesurfer/8.1.0-MCR-R2019b is the standard install but may not be able to run the Freeview GUI due to incompatibilities with the MATLAB runtime other components require.
  • freesurfer/8.1.0-CUDA-MCR-R2019b includes CUDA-enabled Python components for GPU nodes
  • freesurfer-freeview/8.1.0 should be used when you need to run the Freeview GUI

The separate freesurfer-freeview module exists because the standard 8.1 installation may not run Freeview reliably due to MATLAB runtime compatibility issues.

High-speed recon-all

FreeSurfer 8 includes a multi-threaded recon-all mode that can reduce runtime substantially, but it needs a large amount of memory so you will need to request appropriate numbers of threads and memory for this to complete successfully. As a rough guide, expect to request about 85 GB of RAM.

Enable this mode by exporting FS_V8_XOPTS=1 when you submit the job. For example:

fsl_sub -T 240 -R 90 -s 8 --export FS_V8_XOPTS=1 recon_all <my options>

This example requests:

  • 4 hours runtime
  • 90 GB RAM
  • 8 threads

It is a good idea to test with one representative subject first, then adjust the requested memory and runtime based on what you observe. Leave some memory headroom rather than matching the minimum exactly.

Interactive use

If you need graphical tools such as Freeview, start from a shared Linux desktop session and load the appropriate FreeSurfer module there:

For command-line processing, use a shell session on the cluster and load the module before starting your workflow.