4 min read

FreeSurfer: recon-all

First thing first. FreeSurfer (FS from now on) is a powerful software that will reconstruct the cortical surface based on complex calculations taking into account the distance between the white and the cortical grey matter layers. To do so, all you have to do is run a single command wrapping all the steps required: recon-all. Easy-peasy.

However, you have to make up your mind first in whether you want to run this with GNU Parallel (remember this post) or with the options FS counts with by default to speed things up. Let me cover this quickly.

FS allows you to choose between dedicating as many cores as you have to these 34 preprocessing steps by means of OpenMP, or running some of those at each hemisphere simultaneously.

If your weapon of choice is the first one, use the -openmp flag. A subject would apparently take 3 hours or so to finish in modern workstations (+2015).

The second approach requires instead the -parallel flag, and it will make use of 4 threads by default. Do not confuse -parallel (an optional flag from FS) with parallel (a shell tool).

IMPORTANT: Apart from deciding which of the previous will you be using to accelerate computing times, this is the moment to decide whether to run or not the new FS features on segmentation of the amygdala-hippocampal subfields and the brainstem. To perform this, go first to this link and follow the instructions to install the MATLAB Runtime R2014b (NO MATLAB LICENSE REQUIRED). Afterwards, take into account to specify each flag at the end of your recon-all command, such as -hippocampal-subfields-T1 or -brainstem-structures. Accordingly to the FS wiki, these options are very CPU-hungry. I have never tried those, so proceed with caution and if you try this… let me know how the experiment went!

  • Recon-all with GNU Parallel (if I were you, I would pick this one)

Assuming all your niftis (either compressed [.nii.gz] or not [.nii]) are in a folder (“mysubjects”) in your desktop, move them all to the subjects’ directory that FS already counts with.

# renewing permissons to move files to the FS directory
sudo chmod 777 -R $SUBJECTS_DIR 

# moving files ending in ".nii.gz" to the FS subjects' folder
mv ~/Desktop/mysubjects/*.nii.gz $SUBJECTS_DIR/

# moving to the directory where your files are 

Now, type the following to preprocess eight subjects in parallel (NOTE: you can select the number of jobs of your choice).

ls *.nii.gz | sed ‘s/.nii.gz//’ | parallel --jobs 8 recon-all -s {} -i {}.nii.gz -all -qcache

How to tell if it is really working? cd $SUBJECTS_DIR. Supposing eight new folders have been created with the names of the first 8 nifti files (e.g., subj001, subj002, …, subj008), then you’re all set. Otherwise, gently sprinkle some “sudo” at the beggining of the command. Every time the computer is done with a subject, the next one from the “list.txt” will enter into the loop. Now all you have to do is… wait.

  • Recon-all with OpenMP

This will be a little more tricky.

# Going to your folder in the desktop ("mysubjects")
cd ~/Desktop/mysubjects

# Printing all the names of your files without the ".nii.gz" extension in a text file (.txt)
ls *.nii.gz | sed 's/.nii.gz//' > list.txt

# Renewing permissons prior to create folders in the FS subjects' directory
sudo chmod 777 -R $SUBJECTS_DIR 

# Using the list create a folder for each of your subjects with subfolders ("subj001/mri/orig")
for i in `cat list.txt`; do mkdir -p $i/mri/orig; done

# Moving each nifti to its corresponding folder
for i in `cat list.txt`; do mv $i.nii.gz $i/mri/; done

# Moving every folder to the FS directory

Now you’re ready for the final stage, which is putting 8-cores down to work (NOTE: you can select the number of cores that fits you best).

for i in `cat list.txt`; do recon-all -s $i -all -qcache -openmp 8; done

If still need a better lecture on this, please check this Andy Jahn’s video and this post on GNU Parallel, or this awesome math et al tutorial on hippocampal subfields segmentation.

In further posts, I will be covering the recon-all outputs and troubleshooting of naughty “recons”.