Skip to content

FreeSurfer

A software package for the analysis and visualization of structural and functional neuroimaging data from cross-sectional or longitudinal studies.

Homepage Version(s): 7.1.1, 6.0.0

FreeSurfer is a comprehensive software suite developed at Massachusetts General Hospital for the analysis and visualization of human brain MRI data. It is widely used in neuroimaging research for cortical surface reconstruction, brain segmentation, and morphometric analysis.

FreeSurfer provides a full processing stream for structural MRI data, including:

  • Skull stripping, B1 bias field correction, and gray-white matter segmentation
  • Reconstruction of cortical surface models (gray-white boundary surface and pial surface)
  • Labeling of regions on the cortical surface, as well as subcortical brain structures
  • Nonlinear registration of the cortical surface for an individual with a stereotaxic atlas
  • Statistical analysis of group morphometry differences

Using FreeSurfer on RCC Resources#

Before running any FreeSurfer commands, you must load the appropriate module and initialize the FreeSurfer environment.

Load FreeSurfer#

For FreeSurfer 7.1.1:

1
2
3
module load freesurfer/7.1.1
source $FREESURFER_HOME/SetUpFreeSurfer.sh
export SUBJECTS_DIR=/gpfs/home/USERNAME/path/to/output

For FreeSurfer 6.0.0:

1
2
3
module load freesurfer/6.0.0
source $FREESURFER_HOME/SetUpFreeSurfer.sh
export SUBJECTS_DIR=/gpfs/home/USERNAME/path/to/output

Important

The SUBJECTS_DIR environment variable must be set to a writable directory. If this variable is not defined, FreeSurfer will attempt to write output to its installation directory, which is not writable on RCC systems and will result in permission errors.

Example: Running FreeSurfer in Parallel#

The most common FreeSurfer workflow in parallel is the recon-all pipeline, which performs a full cortical and subcortical reconstruction from an MRI scan.

Step 1: Set Environment#

1
2
3
module load freesurfer/7.1.1
source $FREESURFER_HOME/SetUpFreeSurfer.sh
export SUBJECTS_DIR=/gpfs/home/USERNAME/project/freesurfer_output

Step 2: Run recon-all#

1
2
3
4
recon-all \
  -s sub-01 \
  -i /gpfs/home/USERNAME/project/data/sub-01_T1.nii.gz \
  -all

This command:

  • creates a subject directory named sub-01 inside SUBJECTS_DIR
  • imports the T1-weighted image
  • runs the full FreeSurfer processing pipeline (-all)

Output#

After completion, results will be stored in:

1
$SUBJECTS_DIR/sub-01/

Key output subdirectories include:

  • mri/ – volumetric data and segmentations
  • surf/ – reconstructed cortical surfaces
  • label/ – anatomical labels and parcellations
  • stats/ – quantitative morphometric statistics

Because recon-all is computationally intensive, it should be run as a Slurm batch job rather than on a login node.

Example Slurm Script (Single Subject)#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
#!/bin/bash
#SBATCH -J freesurfer_sub01
#SBATCH -N 1
#SBATCH -n 8
#SBATCH -p backfill
#SBATCH -t 12:00:00
#SBATCH --mem=32G

module load freesurfer/7.1.1
source $FREESURFER_HOME/SetUpFreeSurfer.sh

export SUBJECTS_DIR=/gpfs/home/USERNAME/project/freesurfer_output

recon-all \
  -s sub-01 \
  -i /gpfs/home/USERNAME/project/data/sub-01_T1.nii.gz \
  -all

Submit the job with:

1
sbatch freesurfer_sub01.sh

Running FreeSurfer in Parallel for Multiple Subjects#

For studies with multiple subjects, FreeSurfer workflows can be parallelized across subjects using GNU Parallel

Example Slurm Script (Multiple Subjects)#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
#!/bin/bash
#SBATCH -J freesurfer_parallel
#SBATCH -N 1
#SBATCH -n 8
#SBATCH -p backfill
#SBATCH -t 24:00:00
#SBATCH --mem=64G

module load freesurfer/7.1.1
source $FREESURFER_HOME/SetUpFreeSurfer.sh

export SUBJECTS_DIR=/gpfs/home/USERNAME/project/freesurfer_output

cd /gpfs/home/USERNAME/project/data

find . -name "*.nii.gz" | \
  parallel --jobs 8 recon-all \
    -s {.} \
    -i {} \
    -all \
    -qcache

Note

Adjust the number of parallel jobs (--jobs) to match the number of CPUs requested via #SBATCH -n. Each recon-all instance is CPU- and memory-intensive.