5 min read

Installing FSL and FreeSurfer

Hi everyone, it’s been quite a long time since the last entry (a year or so, ba-dum-tsst). In these series of posts, I will explain how to install most of the programs I have used so far for MRI analyses. For me, these are FSL, FreeSurfer, BrainSuite, MRtrix3, and ANTs. This first entry will cover the first two, which are the ones I’ve used the most so far.

Keep in mind that the installation procedure may differ from one SO to another. Here I’m assuming you have installed Ubuntu. That said, I’m addressing on how to get this programs running on this particular Linux distribution. If not your case, then I encourage you to visit each program’s official wiki.

  • FSL

Go here and fill the form. Click on the blue bottom containing the FSL license and scroll all the way down and click accept. Then select your computer OS from the list and hit on register.

Click on the first link to download the latest version of the software (to date, v. 6.0.0).

Now, go to your Downloads folder (remember cd ~/Downloads).

Once there type python fslinstaller.py. Say yes to everything and wait.

NOTE: If by coincidence you hold a newer python version (+3.0) then you will need to slightly modify the last command, typing instead python2.7 fslinstaller.py or whatever suits your particular case best (e.g., python27, python2.7, python26, or python2.6)

Now that the installation is over, you need to configure your shell. This is an important step since all the software described in this and further posts will require customising it.

To do so, you will need to first know which type of shell you’re using. There are roughly two types of shell: bash or csh/tcsh. To figure out which one you’re using type in a Terminal echo $SHELL and you will have the answer. Most people have by default a bash shell.

To configure your bash shell type in a terminal gedit ~/.bashrc (sometimes gedit ~/.bash_profile) and make sure to copy-paste the following line at the end of this weird text file that just popped up in front of you. Save and close this file.

FSLDIR=/usr/local/fsl
. ${FSLDIR}/etc/fslconf/fsl.sh
PATH=${FSLDIR}/bin:${PATH}
export FSLDIR PATH

Among other things that I’m not commenting, this chunk of code will tell the Terminal where to find the binaries (i.e., /usr/local/fsl/bin) required to run each FSL script (e.g., fslbet).

So far so good? Let’s continue with FreeSurfer.

  • FreeSurfer

Go to this link and download the latest version of the software (to date, and similarly to FSL, is v.6.0.0). Click on the Linux link despite it says CentOS (which is not your Linux distribution). Contrary to FSL, this file you’re downloading will take a few minutes more since it’s the entire program (i.e., 4.6 GB) and not an installer (i.e., fslinstaller.py).

Type this piece of code to decompress the whole thing in the path where FSL is also installed.

sudo tar -C /usr/local -xzvf ~/Downloads/freesurfer-Linux-centos6_x86_64-stable-pub-v6.0.0.tar.gz

Now type again gedit ~/.bashrc and paste this at the end. Save and close.

export FREESURFER_HOME=/usr/local/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh

As a final step, go here to register. Check your e-mail because in there you should see the license that the FreeSurfer staff have sent you. Move this file to your FREESURFER HOME directory:

sudo mv ~/Downloads/license.txt $FREESURFER_HOME

Testing the installation. Close your Terminal and re-open it. Now, you should see in top of the window something like this:

-------- freesurfer-Linux-centos56_x86_64-stable-pub-v6.0.0-2beb96c --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME   /usr/local/freesurfer
FSFAST_HOME       /usr/local/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR      /usr/local/freesurfer/subjects
MNI_DIR           /usr/local/freesurfer/mni
FSL_DIR           /usr/local/fsl/6.0

Run a few commands just to make sure everything is working fine (i.e., if the Terminal returns anything that is not an error, then you did well).

For instance type freeview to open the FreeSurfer’s viewer. Type fsleyes to do the same with FSL.

Write recon-all and flirt to test whether these commands from FreeSurfer and FSL are recognised by your Terminal.

Now we can say that the two programs are correctly installed. You can make use of them at this point without any problem.

  • Optional (GNU Parallel)

You’ve everything set and working correctly. However,there’s still something missing, and it will save you TONS of time if you decide to go for it. We will get to that in due time, but the principal feature of FreeSurfer may take a long time to complete. Depending on the computer, each subject’s would require 8 to 15 hours to finish.

The thing is, when you’re preprocessing a single subject, you’re using only one core of your, let’s say, eight-core CPU. Because of this, some very wise and generous people made their way through a fair solution for everyone which is… run everything simultaneously.

Briefly, you’re assigning each one of your CPU-cores to a subject. Then, if your computer has 8 cores, you will process 8 subjects in parallel. This is pure gold, believe me.

It goes without a saying that, for obvious reasons, your workstation will be quite busy for a couple of days. Maybe this would be a good time for bringing your laptop to work until the job is done.

Off-note story: Back in 2017 when I started to preprocessing the sample that I end up using in my first article, I wasn’t aware of any way to speed things up. I mean, I surely knew that others were probably doing way better than me in terms of computing times, but I paid the price of being a rookie at this. It took me 31 days to preprocess 63 subjects. Each participant required 12 hours to finish.

Now, with this trick, I would have had completed this entire step in 4 days (this is, sixteen subjects per day instead of 2).

So, to install GNU parallel in Linux, you have two ways:

  1. Quick installation:
 (wget -O - pi.dk/3 || curl pi.dk/3/ || fetch -o - http://pi.dk/3) | bash
  1. Complete installation:
wget https://ftpmirror.gnu.org/parallel/parallel-20180122.tar.bz2
    bzip2 -dc parallel-20180122.tar.bz2 | tar xvf -
    cd parallel-20180122
    ./configure && make && sudo make install

NOTE: If things are not properly working, please go to this link to find the solution.

Testing the installation. Type parallel. If the installation went OK but still nothing returns, go to the link from above.

There you have it. FSL and FreeSurfer w/GNU-Parallel installed, configured, and ready to run.