How to Customize your Bash Environment for Freesurfer

**The following is for users with BASH as their shell**

In order to run Freesurfer you must set several environment variables and then source the SetUpFreesurfer.sh script. While it may be tempting to set your .bashrc so that this all happens automatically, there is substantial risk in doing so; if any of the resources you automatically call in your .bashrc happen to be offline, your shell will hang and you will not be able to log in or do anything anywhere.

Instead we recommend streamlining the process by using aliases.

1) What are aliases?

Aliases are essentially shortcuts that represent longer commands. By default your .bashrc already includes some aliases. You can see these by running ‘alias’:

nymeria[0]:~$ alias
alias ip='ip -color=auto'
alias l.='ls -d .* --color=auto'
alias la='ls -la'
alias ll='ls -l --color=auto'
alias ls='ls --color=auto'


The line alias ll=’ls -l –color=auto’ means that running the command ll actually runs the command ls -l –color=auto. You can verify this by observing that output from both commands looks identical.

2) Which aliases should I use to set up Freesurfer?

At a minimum you will need to set the variables FREESURFER_HOME and SUBJECTS_DIR.

Your alias should set FREESURFER_HOME to use whichever version of Freesurfer you need. In the screenshot below I have set it to use the Martinos Center installation of 7.0.0.

Your alias should set SUBJECTS_DIR to the path where your subjects’ data resides. In the screenshot below I have set a couple so I can easily switch from analyzing one study to another.

You can also set an alias for sourcing SetUpFreesurfer.sh

Below I have chosen to name my aliases ‘setfsvers’, ‘setknee’, etc. because it makes sense to me. You should choose your own aliases so that they are obvious to you.

alias setfsvers='export FREESURFER_HOME=/usr/local/freesurfer/7.0.0'
alias setknee='export SUBJECTS_DIR=/space/nymeria/1/users/dom/subj/knee0A'
alias setstroke='export SUBJECTS_DIR=/space/nymeria/1/users/dom/subj/strokepts'
alias setupfs='source $FREESURFER_HOME/SetUpFreeSurfer.sh'

3) And where specifically should I put them?

We recommend creating a separate .bash_aliases file to store your aliases. You can do this by running vi ~/.bash_aliases

You then need to edit your .bashrc to source your new .bash_aliases file. You can do this by running vi ~/.bashrc and adding the line source ~/.bash_aliases under the Interactive Settings.

Ultimately you should end up with .bashrc and .bash_aliases like:

nymeria[0]:~$ cat .bashrc
# Source global definitions
if [ -f /etc/bashrc ]; then
. /etc/bashrc
fi

# Only execute the following if interactive shell
if [ "$PS1" ]; then

if [ "$EUID" = "0" ] ; then
PS1='\h[\j]:\W# '
else
PS1='\h[\j]:\W\$ '
fi

umask 002

# Interactive settings
ignoreeof=3
set -o noclobber

# end of interactive
fi

nymeria[0]:~$ cat .bash_aliases
alias setfsvers='export FREESURFER_HOME=/usr/local/freesurfer/7.0.0'
alias setknee='export SUBJECTS_DIR=/space/nymeria/1/users/dom/subj/knee0A'
alias setstroke='export SUBJECTS_DIR=/space/nymeria/1/users/dom/subj/strokepts'
alias setupfs='source $FREESURFER_HOME/SetUpFreeSurfer.sh'

4) And now what?

And now when you open a new terminal you are 3 short commands away from running Freesurfer! You can check that your aliases to set environment variables worked by using echo. You will know you sourced SetUpFreeSurfer.sh correctly when you see output like below.

nymeria[0]:~$ setfsvers
nymeria[0]:~$ echo $FREESURFER_HOME
/usr/local/freesurfer/7.0.0
nymeria[0]:~$
nymeria[0]:~$ setknee
nymeria[0]:~$ echo $SUBJECTS_DIR
/space/nymeria/1/users/dom/subj/knee0A
nymeria[0]:~$
nymeria[0]:~$ setupfs
-------- freesurfer-linux-centos7_x86_64-7.0.0-20200429-3a03ebd --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME /usr/local/freesurfer/7.0.0
FSFAST_HOME /usr/local/freesurfer/7.0.0/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR /space/nymeria/1/users/dom/subj/knee0A
MNI_DIR /usr/local/freesurfer/7.0.0/mni
FSL_DIR /usr/pubsw/packages/fsl/current

5) What if I need more Freesurfer help?

Please visit https://surfer.nmr.mgh.harvard.edu/fswiki

 

Last Updated on March 23, 2023 by Michael S Richards