Installing freesurfer onto you own personal machine can either be straightforward, or tricky depending on what Operating system you are running.

Please follow the link below to free surfer’s wiki, which provides detailed instructions for downloading and installing it onto PC, Mac or an UNIX environment. Also check out the beginner’s guide link as well.

Download and Install Freesurfer
A Freesurfer beginners guide

Please not everyone that this blogpage is still under construction. I posted it so long so that those of you who only need a rough guide, could start so long. Let me know of errors you may spot, and I will gladly correct them. I will try and correct this entry asap!

The following post wil explain in some detail how to run a group analsyis on the CHPC cluster. Please read throught the UNIX tutorials referenced in this blog, before continuing. You will need a basic grasp of the command line. Your files also need to be raw dicom files and us need to be using t1_mprages. Check this on your scan protocol.

Step 1:

Login with (Remember to insert your own user name!):

yourusername@login02: ssh

Now change to the cubic directory…

yourusername@login02: cd /SCRATCH4/cubic

If you get an error message, that says you do not have permission to change to this directory, please let us know! CHPC then still needs to add you to the cubic group.

Step 2: Environment Variables

Next you must setup your “enviroment variables.” To do this, follow this link: How to Install Freesurfer

Step 3: Install our tools for running freesurfer on the cluster.

Run this command, while in the /SCRATCH4/cubic directory (Remember the dot!):
yourusername@login02: .

Remember this command, as whenever we need to update our scripts, you will have to rerun this command from the cubic directory!

Step 4: Copy your files onto the cluster
This step can be potentially done from anywhere. If it seems to slow, you will have to upload your files directly to the cluster.

Start by changing into the subjects directory:

yourusername@login02: cd $SUBJECTS_DIR

Check that you are in the right directory:
yourusername@login02: pwd

Your source files you should get directly from the protea server. To do this, follow this link:

When you have saved all your files into a directory, make sure the directory structure is correct. There should be one main directory containing all your files. Inside this directory should be individual subject files. In each individual files should be a few hundred .IMA files. Navigate using the basic UNIX commands.

Next you have to use the command scp

Change to the directory that contains your main folder with all your subjects in it. The folder that contains all your subjects, we will refer to as your data directory from now on.
You use scp in the following way:

yourusername@login02: scp [data directory or source directory] [target directory]

When copying to the cluser, as it is through a network, you need to give its whole network address: You will also have to tell scp where your freesurfer subjects directory is. To find this, you need to login to CHPC, and run this command:

yourusername@login02: echo $SUBJECTS_DIR

Then you give all this info to scp:

yourusername@login02: scp -vr

Note the -vr flag is for verbose, ie. it prints out all the information, and r is for recursive, that is scp copies all the files in your data dir.

So for instance if your data directory is myfiles_data, located in the /Users/bill/ directory, and your username is bmurray, it will look something like this:

bmurray@login02: scp -vr /Users/bill/myfiles_data

Note: Remember the “/” at the end and before SCRATCH4!

Next, you need to create your target directory. This is where freesurfer will store the finished files. Say you want to call it myfiles_target, you would run the following:

yourusername@login02:mkdir $SUBJECTS_DIR/myfiles_target

Tip: If you get stuck with scp, try googling scp, and figure out what you are doing wrong. You can also try the alternative GUI option:

Also: Check in your subjects directory, when you start to copy, wether the files are correctly copying to the subjects dir. Should you discover you are copying the wrong files, press ctr-C to stop. Simply:

yourusername@login02: cd $SUBJECTS_DIR

Remember that should you leave the CHPC terminal open for few minutes without doing anything, it will lock, or freeze. Simply close the terminal and reconnect.

Step 5: Unpack your dicom files your files onto the cluster

yourusername@login02: cd $SUBJECTS_DIR

Tip: Use tab to complete your commands!

If this does not work, cd ~/clustersurf_bin and check if the script files are there. Should they not be there, try re-running the from the cubice directory. If they are there, run the command directly from that directory as follows:

yourusername@login02: cd $SUBJECTS_DIR

yourusername@login02: . ~/clustersurf_bin/

The following should appear:

Please enter your data directory:
apathy confl_2 confl_9
APATHY confl_3 confl_data_group_1 confl_data_group_5

If your data dir is “confl_data_group_1”, just type it in. Tab wont work here unfortunately.

You should see the following output:

Subject Number 1: ADAMS_RONNIE is submitted to Moab for Dicom unpacking.
Single Subjects dir is /SCRATCH4/cubic/splessis/freesurfer/subjects/EONCS_TEST_DATA/ADAMS_RONNIE/

… for each subject submitted.

Next, check that it is running on the cluster by typing:

yourusername@login02:showq | grep

You will see a list like this:

6717 jfouche Running 8 1:04:24:24 Thu Aug 18 01:06:15
6695 jfouche Running 8 1:19:48:30 Thu Aug 18 16:30:21
6692 jfouche Running 8 1:17:52:21 Thu Aug 18 14:34:12
6708 jfouche Running 8 1:20:28:08 Thu Aug 18 17:09:59
6715 jfouche Running 8 1:06:51:56 Thu Aug 18 03:33:47
6685 jfouche Running 8 1:08:20:32 Thu Aug 18 05:02:23
6745 jfouche Running 8 15:57:20 Wed Aug 17 12:39:11
6729 jfouche Running 8 1:06:50:27 Thu Aug 18 03:32:18
6687 jfouche Running 8 1:15:15:21 Thu Aug 18 11:57:12
6728 jfouche Running 8 1:07:06:53 Thu Aug 18 03:48:44
6712 jfouche Running 8 1:07:42:34 Thu Aug 18 04:24:25
6696 jfouche Running 8 1:20:23:30 Thu Aug 18 17:05:21
6686 jfouche Running 8 1:12:15:43 Thu Aug 18 08:57:34
6711 jfouche Running 8 1:08:19:28 Thu Aug 18 05:01:19
6713 jfouche Running 8 1:07:35:06 Thu Aug 18 04:16:57
6714 jfouche Running 8 1:07:31:54 Thu Aug 18 04:13:45
8682 jfouche Idle 8 1:21:00:00 Wed Aug 17 08:55:00
8684 jfouche Idle 8 1:21:00:00 Wed Aug 17 08:56:07
8686 jfouche Idle 8 1:21:00:00 Wed Aug 17 08:56:07
8687 jfouche Idle 8 1:21:00:00 Wed Aug 17 08:56:07

“Idle” means you need to still wait. “Blocked” means your Idle queue is full. Check again in about half an hour. This process should be quick. Else check periodically till your queue is empty.

To exit the cluster at any time, type “exit”. Don’t worry! This wont cancel your jobs!

To cancel your jobs, run the following command. (Note the capitals.)

yourusername@login02: canceljob ALL

Step 6: Run

Next, change again to your SUBJECTS_DIR and run the next command:

The data dir is your data directory and the subjects dir is the directory which you made to put all the files in. Our example was myfiles_target, if you recall.

To check that listmaker did its job, change to your data directory and run:


If the file does not exist in your data directory, check if might not be still running on the clsuter. Try re-running everything again, and check if you have made any mistakes.

Tip: For more info on moab, follow this link :

Step 7: Start the recon process

Now you are finally ready to recon all your files! This process can take up to a week for a group of a hundred subjects.

yourusername@login02:cd $SUBJECTS_DIR

Enter your subjects dir and target dir as before.

You should see the following output:

Cleaning /SCRATCH4/cubic/splessis/freesurfer/subjects/EONCS_TEST/EXAMPLESUBJECTNAME.2.2008.09/
Subject 44 of 52: EXAMPLESUBJECTNAME.2.2008.09 submitted to cluster

Again use showq, as before to check on the progress of your recon.

Step 8: Checking on your files:

Change to your target directory. You should see a lit of subject names and OUTPUT files. The OUTPUT files are plain text files, which contains info on which subjects it submitted and to where. Use cat to access them, like you did with the file.

Now try the following commands, running them while you are in your target directory, tabbing to complete the subject names:

yourusername@login02:ls EXAMPLE_SUBJECT_20090703_001/scripts/recon-all.done

yourusername@login02:ls */scripts/recon-all.done

yourusername@login02:ls */scripts/recon-all.error

yourusername@login02:ls */scripts/IsR*

You should see which files have finished, which have errors and which are still running.

Use …
yourusername@login02:cat EXAMPLE_SUBJECT_20090703_001/scripts/recon-all.error

… to get the error messages.

Step 9: Copy back to your own PC for error checking:
This time, you will use the same scp command, but in reverse:
scp -vr /Users/bill/

Remember that the output files are far bigger than the input files, so you might have to report at CHPC directly…

For further info, please check out freesurfer’s own wiki:

Here are two standard ways of getting your files off the protea server. If your are using a terminal, you can do the following:

>> ssh

All your old files, that is the ones that were created and stored using the old system, should be stored in /archive1/RESEARCH1 to RESEARCH3. All your new data should be in /archive2/. Just look for your PI’s name. Again, if you do not have access to files that you think belongs to you, let me know. Again, if it belongs to you, you will only be able to read and copy it. This was done to prevent accidental data deletion.

If you would rather using a Graphical User Interface (GUI), read on.

Please not that it is set up so that you cannot change or delete your own files, only copy it. Should you see a message: Access denied, you are either trying to access someone else’s files or your permissions aren’t set correctly. In this case, please let me know! Also, the protea server is only accessible from the UCT and Stellenbosch networks currently.

An important note: Please do not share your password or username with anyone. Rather let them apply for their own login.

Below I describe two methods for downloading files: one for windows and one for Linux. The Mac one should be similar. You will be accessing the server over the network/internet with a Secure Shell Protocol (SSH). This simply means that you need a password to access your files and no one will be able to see what you are doing.

SCP using a GUI in Windows
There are various tools available that can relieve the hassle of copying files over SSH. WinSCP and Bitvise Tunnler are two options for Windows. Here is a tutorial explaining how to use WinSCP in detail. For host, use Set the port to 22 .

SCP using a GUI in Linux
Under Linux, secpanel can be used.

Here is a screenshot of how I setup my connection:

PLease let me know if this does not make sense, or if there are any errors and I will be more than happy to fix this! Feel free to leave a comment!



Here follows a quick description of versioning in Matlab using the open source CVS package. Versioning is used to avoid confusion when multiple programmers work and use the same code. Essential for cross institutional collaboration. I chose CVS as it is freely available on both UNIX and MAC platforms, is well supported and is simple to use as part of the standard Matlab editor.

Step 1: Enable Source Control in Matlab
This is done through the Matlab preferences section. Under “General” click on “Source Control” and chose CVS.

Step 2: Setup your CVS environment variables

CVS uses an environment variable called $CVSROOT, to specify the location of the “CVS server”, ie. the master copy of the files that everyone “Checks out” and
“Checks in” again. Setting this is simple (See basic UNIX tutorials if you get stuck!):

First create a “cvsrep” directory. I suggest using a dropbox account to start of with. Make sure you all use the same file!
If you are using BASH, change your ~/.profile to inlcude:

# Set CVS enviroment
export CVSROOT=(The full path of your cvsrep directory in Dropbox)
export CVSEDITOR=emacs

To test, type:

>>echo $CVSROOT
>>(The full path of your cvsrep directory in Dropbox)

Step 3: Do an initial check-out of all the files.

>>cd (The full path of your cvsrep directory in Dropbox, then one of the individual directories.)

CVSROOT current matlab_toolbox max_tools pathtool

I want to work on a directory called ~/working_dir. So I change to my working_dir:
>> cd ~/working_dir

It is important that you are in the working directory! Now to checkout all the file, ie make copies of my cvsrep matlab_toolbox directory in my working_dir, I type:
>>cvs checkout matlab_toolbox

Do this for all the toolboxes you will edit. Then, open one of the .m files in your standard matlab editor. In the file menu, go to source control > check out.
From here, follow the standard MATLAB instructions. Every time you wish to change code, check it out and lock it! Then finally, when finished, check it in with a comment.

Let me know on how to make these instructions more accurate/user friendly!

Here are my sources:

CVS cheatsheet
Official MATLAB source control interface.


Following is the protocol according to which we will be looking at the freesurfer recon-all results.

Step 1:
Turn computer on😉

Step 2:
We have 5 groups of scans, with 10 subjects each. All the scans have been reconstructed already, and are one the USB HD we will be giving you.
First we will be copying each subject into the subjects directory so that tkmedit and tksurfer can find them.

Step 2a:
Where is my $SUBJECTS_DIR?

Go to the command prompt: (Terminal for Mac and Linux)

Type in:


This should show something like:


This does not have to match the above, you just need to have it identified. Otherwise, re-setup your freesurfer environment variables.

MAC users: Try typing: >>open $SUBJECTS_DIR)

Linux users: Open the above directory in your file browser.

Drag and drop each subject into your $SUBJECTS_DIRECTORY. If some files are called the same, you will have to rename them! It is important that you drag and drop each subject individually into the subjects directory so that none are contained inside another file folder.

So when you type:


…you should get a list of the individual subject names!

Step 3
>>tkmedit (insert subject name here) orig.mgz (lh.orig) rh.orig -aparc+aseg

…or (See comment below…)

>>tkmedit (insert subject name here) orig.mgz -surfs -aparc+aseg

(Onthou: Moenie die hakkies intik nie!)

Tip: When you type CTRL-G, the atlas will disappear, making the red and green lines more visible.

The green line is where the white matter ends and the green line is where the CSF begins and the grey matter ends.

Tip: CTRL B is for the contrast settings

Try sticking to one set on contrast values for your screen.

Now look through each scan, using the arrow keys, for about 2 seconds per slice. Remember, when in doubt, try changing to axial/coronal views. Most times freesurfer will do it correctly in anatomically normal scans. Even if you find a big error, make a note and look through the other subjects if it reoccurs.

When we meet again, we will decide together what we except as correct or incorrect. To oriantate yourself, take a look at the standard subject “bert” that comes with freesurfer. This subject is correctly reconstructed.

Step 4

Finally we will look at the surface, if it is smooth, and does not have holes or spikes in it. These surfaces must be smooth.
>> tksurfer bert lh inflated
>> tksurfer bert rh inflated

Thanks again everyone for your valued efforts! Watch this page for updates!

Here are a few links to the relevant freesurfer info. Please have a look at the validation studies as it gives a goo indication what freesurfer can and cannot do!

Official Freesurfer beginner’s Guide
Documentation (Scroll down)
Official Freesurfer tutorial
Freesurfer Mailing list


Connecting to CHPC

Posted: June 20, 2010 in HOW-TO's

Since CHPC is a secure Linux cluster, one needs a login and a password. To obtain these you need to apply for one click here. Anyone involved in neuro-imaging can request access to the CHPC cluster. Take your time to read through the Usage Policy of the CHPC cluster to see if your work will require High Performance computing.

Don’t be intimidated by the request form though! If you are planning to do medical neuro-imaging research, chances are that you are going to need access to a large cluster sooner or later. Just make clear why and you need of the cluster. Should you require any assistance, please feel free to contact the CHPC support at . After this, contact us and we will add you to our “cubic” group. This will give you access to our encrypted workspace.

Important Note:
Once you have a login and password, do not share it with any other analysts. Rather let them get their own logins. It could compromise the security of the cluster.

Once you have a login and password, you will need a SSH client. If you are using a Mac or Linux, you can use your terminal to gain access. If you are using windows, you must download software such as Putty.

When you are ready, enter the following line into your terminal:


Should you require to launch a GUI, enter the following:

ssh -X

The “-X” tells the software that you are going to use X-windows. If you are using Linux, you dont need to install any new software, as you are already using X-Windows. If you are using Mac, you must install X11 for Mac from your install DVD.

Note: SSH may tell you that “The authenticity of host ‘ (’ can’t be established.” This is only since you are connecting for the first time, and this is normal! Say: “Yes”. It should then say: “Warning: Permanently added ‘,’ (RSA) to the list of known hosts.”

You should be then prompted for a password. Should you be successful, you should see the following:


For more information on how to use the system please check Start_doc_SUN.txt on /SCRATCH4

Contact (0216582740/58/60) for Support from 8h00 to 16h30 working days

If you see the above message, you are now logged in on the Sun cluster. Congratulations! You are ready to enter the world of High Performance Computing. Here be Dragons.

Environment variables are place holders where UNIX keeps important information. Programs such as FSL and Freesurfer use them extensively as they are very configurable and have endless uses. They are usually store as capital letters with a “$” attached to their front. For example, if you want to see what the “$FSL_DIR” variable holds, just type:

echo $FSL_DIR

This should show you what is in the variable. If it returns an error message, or an empty line, it is not defined! Not to worry though, as it is fairly simple to change them. How you change them, depends on which “shell” you are working in. So how do you find this out? Type:

echo “$SHELL”

It should return something like:


The rest of this tutorial assumes you are using the “bash” shell. Most of the information your bash shell needs to work, is contained in the .profile script in your home directory. To tell Freesurfer and FSL where they are going to work, add the following to your .profile by typing:

Here is how to install fsl and freesurfer into your own home directory:

cp -vr /SCRATCH4/cubic/freesurfer-Linux-centos4_x86_64-stable-pub-v4.5.0-full.tar.gz /SCRATCH4/cubic/YOURUSERNAME
tar vxfz freesurfer-Linux-centos4_x86_64-stable-pub-v4.5.0-full.tar.gz
cp -vr /SCRATCH4/cubic/fsl-Linux-ubuntu_x86_64-CHPC.tar.gz .
tar vxfz fsl-Linux-ubuntu_x86_64-CHPC.tar.gz

emacs ~/.profile

Now copy/paste the following into the emacs window at the end of the file using either Ctrl-C Ctrl-V or highlighting the text and pressing the middle mouse button.

Remember to replace YOURUSERNAME with your own username!

source ${FSLDIR}/etc/fslconf/


To save in emacs, press Ctrl-X Ctrl-S, then to exit press Ctrl-X Ctrl-C.

To make your life easier, should you choose to use emacs as your editor, at these lines to the .emacs file by typing:

emacs ~/.emacs

… and paste the following at the end of the file:

(setq-default auto-fill-function ‘do-auto-fill)
(global-font-lock-mode 1)

To check if you have done everything correctly, type:
. ~/.profile
The following should appear on your screen:

——– freesurfer-Linux-centos4_x86_64-stable-pub-v4.5.0 ——–
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FSFAST_HOME /SCRATCH4/cubic/YOURUSERNAME/freesurfer/fsfast
SUBJECTS_DIR /SCRATCH4/cubic/YOURUSERNAME/freesurfer/subjects
MNI_DIR /SCRATCH4/cubic/YOURUSERNAME/freesurfer/mni