Retinotopy in Freesurfer–CNL Protocol

by Kyle on June 5, 2013

CNL ROP – Retinotopy Workstation Setup – Windows 7 – 64 –bit

Installing Xubuntu on Virtual Box
Analyzing the Structural Data with recon-all
Analyzing the Functional Data with FSFAST
Visualize Results with tksurfer

A special thanks to Dr. Paige Scalf and her student Laura Cacciamani for compiling and creating many of the sections of this document. For more help and references to which I also am indebted see: This also provides a nice psychtoolbox script that can be used to collect retinotopy data. And a script that can be used to analyze preprocessed retinotopy data. This does not however analyze the functional data in terms of preprocessing and coregistration, and we found it easier to do all the steps in FSFAST in freesurfer. – Explains cutting the occiput surface, and some of the process, but the steps are outdated for old freesurfer versions – The most authoritative but least ellaborative instruction. I don’t find his automated way of viewing the results as effective as the one shown below based on the SamPenDu tutorial.


SUMMARY – (More details and links below).

This explains how to setup the environment for Retinotopy analysis for OPA. It explains how to use a windows 7 64-bit pc to install Matlab, SPM 8, and VM Virtual Box.

SPM 8 is used to convert .IMA raw DICOM files from the BIC Siemens 3T Trio scanner.

Virtual Box is then used to create and install and virtual Xubuntu environment.

-In Xubuntu, freesurfer is installed, the neurodebian archive is used to install FSL, and matlab is downloaded, mounted, and installed (freesurfer required FSL and matlab for the analysis).

-A shared folder is setup between windows and the virtual Ubuntu environment.

The Retinotopy analysis is then performed on the output of SPM 8 in Xubuntu.



XUBUNTU on Virtual Box

1) On the windows 7, 64bit host, install matlab 2012a and Install SPM 8 and set the path to the installed toolbox in matlab

2) Restart Computer > Start BIOS > Intel or AMD > Enable Virtual Hardware (‘You will encounter a ‘VT-x’ error later when trying to launch the vm if this is not enabled.)

3) Download a copy of Xubuntu 12.10 64-bit from

4) Either VirtualMount the CD, or burn a copy of the image onto a DVD to install the OS

5) Download VirtualBox 4.2.12 for Windows

6) In VirtualBox Click New clip_image002

a. Name: Ubuntu64, Type: Linux, Version: Ubunut (64 bit)

b. Memory size – 10000 MB – 10GB?

c. Hard drive > Create a virtual hard drive now > Create

d. VDI > Next> Fixed Size > 100 GB > Click folder to browse to HD location (e.g. E:/VM_disks)> Create

7) In VirtualBox Click Settings clip_image003

a. General Menu > Advanced Tab > Shared Clipboard > Bidirectional

b. System Menu > Motherboard Tab > Extended Features > Check Enable IO API

1. > Processor Tab > Processors > 2, Extended Features > Check Enable PAE/NX

2. Acceleration Tab > Check Enable VT-x/AMD-V, Check Enable Nested Paging

c. Display Menu > Video Memory > 24 MB, Uncheck Enable 3D Acceleration and Enable 2D…

d. Shared Folders Menu > Click +Folder to add > Create Folder called “UbunuShare”

8) In VirtualBox – Click Start clip_image004

a. Select Drive

b. Instal Xubuntu from the disk

9) Create a shared folder from windows to Ubuntu with these instructions called UbuntuShare

be sure to create a text file called mount with, the password is at the top of the terminal

sudo mount -t vboxsf UbuntuShare /home/virtualuser/WinShare


10) Back on the Ubuntu Virtual Box – CTRL F – fullscreen, if you start the virtual machine again be sure to remount the shared folder in the terminal (the password is at the top)


11) Download Freesurfer 5.1.0 64-bit –

a. Register your copy of Freesurfer here Create the .license file from the email contents between the lines.


12) Use Neurodebian to install the FSL components you need from here (I had to run twice to get FSL 5.0), check on the application menu that it installed


13) Download matlabR2012b_UNIX.iso from

a. Open a terminal and mount the .iso to a new folder and install

mkdir /MATLABmedia

mount -t iso9660 -o loop ~/downloads/matlabR2012b_UNIX.iso /MATLABmedia

cd /MATLABmedia


b. REMEMBER – you will need to be on CITES VPN on the WINDOWS PC for matlab to work

14) Edit the bash startup script to initialize everything correctly when you open the terminal:

a. In your home folder, show hidden files, open “.bashrc”

b. Add the following lines to the end and save (Where “karl” is whatever your Ubuntu username is

#Freesurfer setup

export FREESURFER_HOME=/home/karl/freesurfer

export FSLDIR=/usr/share/fsl/5.0



# Mount shared folder

sudo mount -t vboxsf UbuntuShare /home/karl/WinShare


Now we can finally do the analysis protocol


Structural file conversion from scanner output

15) Run spm > click fMRI > click Batch > Click SPM menu > Util > DICOM Import

DICOM FILES – Select all the slice files from the scanner output MPRAGE folder (e.g. *.IMA)

Output Directory – Select the shared folder from 2)

Output image format – select .nii

Functional file conversion from scanner output

Convert to .nii (do for each retinotopy type)

16) – Run spm > click fMRI > click Batch > Click SPM menu > Util > DICOM Import

This is very similar to 4, but now uses the functional scans, and has an extra stem to combine slices over time into a 4D .nii file

DICOM FILES – Select all the slice files from the scanner output EPI_ folder (e.g. *.IMA)

Output Directory – ** Select the same EPI_ folder as the slices, there is one more step below

Output image format – select .nii

Convert to 4D (do for each retinotopy type)

6) Run spm > click fMRI > click Batch >Click SPM menu > Util > 3D to 4D file conversion

3D volumes – select all the .nii files in the data directory from 5a)


In the shared (ubunto-windows) folder,

-rename the MPRAGE .nii file with the subject ID (e.g. MS_041013.nii)

-create four folders (001, 002, 003, 004) for each retinotopy direction and type (POLARPOS, POLARNEG, ECCENPOS, ECCENNEG).

-Go to the data directories where your scanner output files are, and copy the newly created (5b) f.nii files from each of the respective EPI folders to each of the new folders in the shared folder. Make sure to put the correct files in the correct folder depending on the order of the tasks recorded in the run sheet (e.g polar positive is EPI_Vis_1 and should go in 001, polar negative is 2 and should go in 002, eccentric positive is 3, and eccentric negative is 4.


In Xubuntu > Open a terminal

8) Run recon-all on the structural data, use the -i command to import from the shared folder and create a new subject directory structure in the freesurfer subject directory (this will take all day).

recon-all -s MS_041013 -i WinShare/MS_041013.nii -all

1. Cut occiput surface
Run command

tksurfer MS_041013 lh inflated

2. to display the inflated left hemisphere.
Rotate the brain until the medial surface is facing you.
Then select points along calcarine fissure and press button “Cut line”.
Select 3 points to define the cutting plane: 2 on medial side and 1 on lateral side. Choose a 4th point to specify which portion of surface to keep and press button “Cut plane”.

Save (File > Patch > Save As) as file lh.occip.patch.3d.
(To know how to cut full brain, check out this PDF)

3. Flatten occiput surface

cd to the subject’s “surf” directory and run

mris_flatten -w 0 -distances 20 7 lh.occip.patch.3d  lh.occip.patch.flat

To visualize the patch, you can first load the subject’s inflated surface, then File > Patch > Load Patch …
Flattening takes 1-2 hours.

4. Repeat step 2 and 3 for the right hemisphere.






Setting up for the analysis:

· Your directories MUST follow this flow:

o Subjects/SUBJECTID/FunctionalDir/RunDir/Rawfuncdata.nii

o subjects/MS_041013/Retinotopy/001/f.nii


o subjects/MS_041013/Retinotopy/001/rtopy.par


o subjects/MS_041013/Retinotopy/002/f.nii …

· in freesurfer/subjects/SUBJECTID Create a text file called “subjectname” (NO .txt on the end)

o In it should contain ONLY your subject’s name (i.e. MS_041013)

o This subject name must match the freesurfer subject name (here SUBJECTID; created when you did the recon-all command), so make sure it’s right

· Folder 001 and 002 are for Polar, 003 and 004 for eccen; In each of the 001, 002, 003, and 004 directories create a .par files (a text file with extension .par)

o They should both be called the same thing (i.e. “rtopy.par”)

o Should contain the following:

§ In folder 001:

stimtype polar

direction pos

§ In folder 002:

stimtype polar

direction neg

§ In folder 003:

stimtype eccen

direction pos

§ In folder 004:

stimtype eccen

direction neg

9)In a new window, open up the shared directory, and copy and paste the four folders into the Subject directory/Retinotopy folder with the four matching folders, the files will copy into their respective folders. Make sure the functional data matches what is written in the rtopy.par file.

10) You will also have to convert each of these f.nii files to add the TR probably:

cd 001

mri_convert f.nii f.nii -tr 2000

cd ..

cd 002

mri_convert f.nii f.nii -tr 2000

cd ..

cd 003

mri_convert f.nii f.nii -tr 2000

cd ..

cd 004

mri_convert f.nii f.nii -tr 2000

cd ..



First-level GLM analysis:

Note: for all of these commands, you must be in the main project directory

· Preprocessing:

o preproc-sess

§ -s <subject>

§ -surface self lhrh

§ -fsd <FunctionalDirectory>

§ -mni305

§ -fwhm <number>

· For no smoothing, set to 0

o Example:

preproc-sess -s MS_041013 -surface self lhrh -fsd Retinotopy -mni305 –fwhm 5


· Make the design:

o Mkanalysis-sess

§ -a <analysis directory>

§ -surface self lh

§ -TR <TR value, in seconds>

§ -retinotopy <length of 1 cycle, in seconds>

§ -paradigm <.par file>

§ -fsd <FunctionalDirectory>

§ -fwhm <number>

o Example:

mkanalysis-sess -a Retinotopy.MS_041013.lh -surface self lh -TR 2 -retinotopy 36 -paradigm rtopy.par -fsd Retinotopy -fwhm 5

· Analyze:

o selxavg3-sess

§ -a <analysis directory>

§ -s <subject directory>

o Example:

selxavg3-sess –a Retinotopy.MS_041013.lh –s MS_041013


Compute the field sign?

fieldsign-sess -a Retinotopy.nils.lh -sphere -s nils

fieldsign-sess -a Retinotopy.nils.rh -sphere -s nils


To view the data:

tksurfer <subject> <hemisphere> inflated

· OPTIONAL – Under file > Patch > Load Patch… > Browse… > SUBJECTID/surf/lh.occip.patch.flat or rh

· Ctrl + Right Click Curvature toggle, Load Curvature, Press Ok

· Under file > Load overlay

o Navigate to ProjectDir/SessionDir/FuncDir/func.subject.hemisphere/[polar/eccen]

o Load real.nii.gz into overlay 1, close, reopen and and imag.nii.gz into overlay 2 (both no registration necessary)

· Under view >Overlay Layer > Select real.nii.gz

· Under view > Configure… > Overlay…

o Under “color scale”, select RBG wheel

o Under “display options”, select “complex”

o Check “Ignore Zeroes in Histrogram”

o Change thresholding as necessary (I used .25-.8)

o Press Apply

· FOR POLAR ONLY – Under view à configure à Phase encoded data display

o Change angle cycles to 2

Create Legend:

Comments on this entry are closed.

Previous post:

Next post: