1. Unix Tutorial for FreeSurfer Users
Allison Stevens
-covers only basics: cd, copying files; no scripting
-basic understanding of unix necessary to use FreeSurfer
-not comprehensive, just to get you through course

2. What is Unix/Linux? An operating system (like Windows and OS X)
Linux is the free, modifiable, and redistributable version of Unix
Why use it?
Use the term Linux interchangeably with Unix sometimes.
The data that comes off the scanner is lots of data – hundreds of slices and within each slice hundreds to thousands of voxels.

3. What is Unix/Linux? An operating system (like Windows and OS X)
Linux is the free, modifiable, and redistributable version of Unix
Why use it?
power to write many scripts with many commands to work with lots of data
to use computer resources on the network efficiently, such as clusters
The data that comes off the scanner is lots of data – hundreds of slices and within each slice hundreds of voxels.

4. Getting Started
Communicate with operating system through a “shell” or terminal window.
For course-provided Linux computers:
Double click Terminal icon on Desktop
For Macs:
Applications > Utilities > XQuartz (double click)
Applications > Utilities > Terminal
compare to Windows GUI  hit Start and see icons of programs to choose from. Similar to DOS.
-to run programs, must type a command for what you want to do on the command line.

5. Warm Up Type: and hit enter. date Mouse needs to be in window to work
Commands in boxes
This is how you’ll interact with FreeSurfer

6. Warm Up Type: and hit enter. Should see date
Mon Apr 6 8:05:24 EDT 2009

7. Warm Up Type: and hit enter. Should see and hit enter. date
Mon Apr 6 8:05:24 EDT 2009
cal

8. Warm Up Type: and hit enter. Should see date
Mon Apr 6 8:05:24 EDT 2009
April 2009
Su Mo Tu We Th Fr Sa
cal

9. Directories Unix uses a hierarchical file system
(think folders in Windows)
Even though you see just a blinking cursor, you now have access to all your directories and files just at that one line.

10. Directories Unix uses a hierarchical file system
(think folders in Windows)
Home is like “My Computer”
Home is like My Computer

11. Directories Unix uses a hierarchical file system
(think folders in Windows)
Home is like “My Computer”
Like “My Documents”

12. Directories Unix uses a hierarchical file system
(think folders in Windows)
Home is like “My Computer”
Like “My Documents”
Like “My Photos”

13. Directories Unix uses a hierarchical file system
(think folders in Windows)
Home is like “My Computer”
Like “My Documents”
Like “My Photos”
picture.jpg

14. Location path: /MyComputer/MyDocuments/MyPhotos Type:
and hit enter. Should see
shows “present working directory” or current location as a path
/home/nmrclass OR
pwd
/Users/YourName
-notice there are no spaces in between the names. Unix does not like spaces so please avoid them
-the path shows, at the end, the current directory you are in and all the directories you need to go through to get to it.
-in tutorials, will need to go into directory where data is stored
-check on your current location using pwd whenever you encounter an error to make sure you’re in the right place

15. Opening a Directory Not double clicking Type command to “open”
-will show commands for opening directories but different for files and programs
-may see gnumeric or ooffice in tutorials
Commands to open files will differ

16. Navigating Directories
“change directory”: move into a folder
“list”: see contents of directory
cd __ ls
ls __
cd *space* and then the name of the directory you want to change into

17. Navigating Directories
“change directory”: move into a folder
“list”: see contents of directory
cd __ ls
ls __
Desktop matlab tmp TUTORIAL_DATA

18. command -option1 –option2 file
Anatomy of a Command
command -option1 –option2 file
command - -help
-option often called flag
-this format is true for Unix and FreeSurfer commands
-two dashes before the word “help”

19. command -option1 –option2 file
Anatomy of a Command
command -option1 –option2 file
command help
-two dashes before help
-argument could be a file or volume
Try:
ls --help

20. Directory Contents List contents of directory you are in
lists names of directories/files ls
ls -a
ls -l
ls -lrt

21. Directory Contents List contents of directory you are in
lists names of directories/files
lists hidden files too ls
ls -a
ls -l
ls -lrt
.cshrc
.bashrc
.alias

22. Directory Contents List contents of directory you are in drwxrwx---
lists names of directories/files
lists hidden files too
lists file details
drwxrwx--- ls
ls -a
ls -l
ls -lrt
-ownership of file as well as date it was created and size
user
group
others

23. Directory Contents List contents of directory you are in
lists names of directories/files
lists hidden files too
lists file details
lists recent files last ls
ls -a
ls -l
ls -lrt
r could mean recursive or reverse

24. Save Some Time Filename Completion hit Tab key should see hit enter
History
hit key should see
ls Des
ls Desktop
-case sensitive
-keep hitting up arrow key to see other commands you typed in the past
Ctrl+a on mac goes to home; ctrl+e goes to end
Option + left right arrows jumps to spaces
ls Desktop

25. /home/nmrclass/practice
Changing Directories
makes a new directory “practice”
changes to directory “practice”
mkdir practice
ls -lrt
/home/nmrclass
pwd
should see
cd practice
Always do ls and pwd afterwards to see what changed.
pwd
/home/nmrclass/practice
should see ls
should see
Nothing!

26. Changing Directories

27. Changing Directories makes folder “stuff” inside practice
mkdir stuff
makes folder “stuff” inside practice ls
should see “stuff”

28. Format > Make plain text
Using an Editor
If using a Mac:
Type: I could write a script.
File > Save (Buffer)
File > Exit emacs
should see “mynotes.txt”
emacs mynotes.txt
open -e mynotes.txt
Format > Make plain text
File > Save
Ctrl+x, Ctrl+c to exit and save in emacs when opened within a terminal ls

29. Format > Make plain text
Using an Editor
If using a Mac:
Type: I could write a script.
File > Save (Buffer)
File > Exit emacs
should see “mynotes.txt”
gedit mynotes.txt
open -e mynotes.txt
Format > Make plain text
File > Save
Ctrl+x, Ctrl+c to exit and save in emacs when opened within a terminal ls

30. Using an Editor

31. Copying files is the copy command learn all the options or “arguments”cp
cp --help
learn all the options or “arguments”
cp mynotes.txt stuff
-can use tab with mynotes.txt
“less” is similar to more, however it lets you scroll up and down pages. Must enter ‘q’ to get out of less command.
cd stuff ls
more mynotes.txt

32. Copying files is the copy command learn all the options or “arguments”cp
cp --help
learn all the options or “arguments”
cp mynotes.txt stuff
“less” is similar to more, however it lets you scroll up and down pages. Must enter ‘q’ to get out of less command.
cd stuff ls
less mynotes.txt

33. /home/nmrclass/practice/stuff
Changing Directories
shows one directory up
ls ..
can also do (but don’t right now):on
cd ..
cd ../..
ls ../..
goes up two!
pwd
/home/nmrclass/practice/stuff
should see

34. Copying / Moving files Could also use do:
cp mynotes.txt myothernotes.txt
mv myothernotes.txt hernotes.txt
mv is like cut and paste
mv hernotes.txt

35. Removing Files should be in “stuff” pwd ls rm mynotes.txt ls
Gone forever; no trash can

36. Things to know Case sensitive Does not like spaces in file names
(e.g. filename.txt vs. file name.txt)
Ctrl+c kills a process & brings back command prompt
Type ‘q’ to quit the program ‘less’
Highlight & middle click to copy & paste
Use ‘&’ to open a program in the background
Cannot open a 2nd program if do not have a command prompt

37. Review no double clicking mkdir ls cd pwd emacs, gedit, vi, pico cp rm
more commands in reference sheet hand out

38. Using FreeSurfer
With FreeSurfer, certain variables must be set in order to use it correctly:
FREESURFER_HOME
SUBJECTS_DIR
tell Operating System where FreeSurfer is
-for the tutorials today, FREESURFER_HOME will already be set for you. But when you go home and use FreeSurfer on your own machine, you will need to make sure you have these variables set before you can begin working with FreeSurfer.
-during the course SUBJECTS_DIR will change often, so pay attention to instructions at top of tutorial and change it accordingly
tell FreeSurfer where data is

39. Required Variables To use FreeSurfer you’ll have to do:
setenv FREESURFER_HOME /home/apps/freesurfer
tell Operating System where FreeSurfer is
source $FREESURFER_HOME/SetUpFreeSurfer.csh
-Set up environment or initialize freesurfer (see setenv a lot)
Can set up .profile or .cshrc to always run these commands for you for every terminal window opened
source this script to get your computer ready to use FreeSurfer (sources other scripts & sets other variables)
setenv SUBJECTS_DIR /path/to/data

40. Required Variables To use FreeSurfer you’ll have to do:
export FREESURFER_HOME=/home/apps/freesurfer
tell Operating System where FreeSurfer is
source $FREESURFER_HOME/SetUpFreeSurfer.csh
-use ‘export’ for bash
Can set up .profile or .cshrc to always run these commands for you for every terminal window opened
source this script to get your computer ready to use FreeSurfer (sources other scripts & sets other variables)
export SUBJECTS_DIR=/path/to/data

41. setenv SUBJECTS_DIR /path/to/data
Required Variables
To go to location of your data:
$ means take the value of the variable
setenv SUBJECTS_DIR /path/to/data
cd $SUBJECTS_DIR
-Set up environment or initialize freesurfer (see setenv a lot)
-cd SUJBECTS_DIR is shortcut to cd /path/to/data
-in tutorial will often have to cd $SUBJECTS_DIR

42. setenv SUBJECTS_DIR /path/to/data
Required Variables
To go to location of your data:
$ means take the value of the variable
setenv SUBJECTS_DIR /path/to/data
cd $SUBJECTS_DIR
aka
cd /path/to/data
-Set up environment or initialize freesurfer (see setenv a lot)

43. setenv TEST_VARIABLE yourfirstname$
How ‘echo’ works:
To set a variable:
To check what a variable is set to:
echo Allison is cool.
setenv TEST_VARIABLE yourfirstname
echo prints to the screen whatever you type after it
echo $TEST_VARIABLE

44. echo $FREESURFER_HOME
Required Variables
With FreeSurfer, certain variables must be set in order to use it correctly:
FREESURFER_HOME
SUBJECTS_DIR
tell Operating System where FreeSurfer is
tell FreeSurfer where data is
To check variables
echo $FREESURFER_HOME
echo $SUBJECTS_DIR

45. More Help
Links on Wiki under “Unix Tutorial”
Glossary of Unix commands

46. The End
Good Luck!

47. Intro to FreeSurfer Jargon
voxel
surface
volume
vertex
surface-based
recon
cortical, subcortical
parcellation/segmentation
registration, morph, deform, transforms (computing vs. resampling)

48. What FreeSurfer Does…
FreeSurfer creates computerized models of the brain from MRI data.
-"IR prepped SPGR" (inversion recovery prepared SPGR) is GE version of MPRAGE
-if did this manually, would take a long time
Input:
T1-weighted (MPRAGE)
1mm3 resolution
(.dcm)
Output:
Segmented & parcellated conformed volume
(.mgz)

49. Intro to FreeSurfer Jargon
voxel
voxel like pixel
-tons of pixels make up this image, but with scan data we call them voxels (because they have a volume – and that’s how we can already get some meaningful info from this image: volume of brain)

50. Intro to FreeSurfer Jargon
-got all this data, want to divide it up to have some meaningful info about this subject
-surface is a cortical boundary (gm or wm)
surface

51. Intro to FreeSurfer Jargon
-think of surfaces not only in terms of this 2D slice but also in terms of how they would look over the entire 3D structure of a brain
-what boundary over all the wm in brain looks like; what boundary over all the gm in brain looks like
surface

52. Intro to FreeSurfer Jargon
vertex
-surfaces are made up of many tiny points which are the vertices of the surface.
-it is here we store information about surface (the point that we sample measures at)
-surface-based analysis involves any value you can sample onto the surface

53. Recon “recon your data” …short for reconstruction
…cortical surface reconstruction
…shows up in command recon-all
reconstruction of surfaces (creation of those boundaries of gm and wm)
recon-all is how you process data in freesurfer
“check your recons” refers to output

54. Recon

55. Volumes orig.mgz T1.mgz brainmask.mgz wm.mgz filled.mgz
(Subcortical Mass)
-usually referring to mri data; also referring to mgz files created by freesurfer
-volume of subcortical regions – actual measurement

56. Cortical vs. Subcortical GM
-surfaces not used to get measurements on subcortical so it’s okay that they are wonky there
sagittal
coronal

57. Cortical vs. Subcortical GM
-subcortical masked out
sagittal
coronal

58. Parcellation vs. Segmentation
(cortical) parcellation
(subcortical) segmentation
-parcellation refers to division of cortical areas; segmentation refers to division of subcortical areas, sometimes also segmentation of wm and gm

59. Intro to FreeSurfer Jargon
voxel
surface
volume
vertex
surface-based
recon
cortical, subcortical
parcellation/segmentation
registration, morph, deform, transforms (computing vs. resampling)

60. FreeSurfer Questions Search for terms and answers
to all your questions in the Glossary, FAQ, or
FreeSurfer Mailing List Archives
-lectures followed by hands on tutorials
-firefox opens to the schedule page. from there links to lecture slides and tutorials. follow along

61. Registration
Goal:
to find a common coordinate system for the input data sets
Examples:
comparing different MRI images of the same individual (longitudinal scans, diffusion vs functional scans)
comparing MRI images of different individuals

62. Inter-subject, uni-modal example
Flirt 9 DOF
target
subject
Flirt 6 DOF
Flirt 12 DOF
12/13/2011 62

63. Linear registration: 6, 9, 12 DOF
subject
target
Flirt 12 DOF
Flirt 9 DOF
Flirt 6 DOF 63

64. Linear registration: 6, 9, 12 DOF
Flirt 12 DOF
Flirt 9dof
subject
target
Flirt 6dof

65. Linear registration: 6, 9, 12 DOF
Flirt 12 DOF
Flirt 9 DOF
subject
target
Flirt 6 DOF

66. Intra-subject, multi-modal example
before spatial alignment
after spatial alignment

67. before spatial alignment
after spatial alignment

68. before spatial alignment
after spatial alignment

69. Inter-subject non-linear example
target
CVS reg

70. Some registration vocabulary
Input datasets:
Fixed / template / target
Moving / subject
Transformation models
rigid
affine
nonlinear
Objective / similarity functions
Applying the results
deform, morph, resample, transform
Interpolation types
(tri)linear
nearest neighbor

72. Writing Scripts Putting multiple commands together.
Automatically running a sequence of commands
Example: create a file named my_first_script.csh with the contents:
#!/bin/csh
setenv name FreeSurfer
echo I love $name !
% chmod u+x my_first_script.csh
% ./my_first_script.csh

73. Loops in Scripts You can create loops, if statements, …
Example: create a file named my_first_loop.csh with the contents:
#!/bin/csh
foreach name (‘Bill Murray’ ‘Wes Anderson’)
echo I love $name !
end

74. Inputs to Scripts You can create take inputs from the command line
Example: create a file named my_first_IO.csh with the contents:
#!/bin/csh
echo The $0 command is called with $#argv parameters
echo parameter 1 is $1
echo parameter 2 is $2

75. Required Variables To use FreeSurfer you’ll have to do:
setenv FREESURFER_HOME /home/apps/freesurfer
tell Operating System where FreeSurfer is
source $FREESURFER_HOME/SetUpFreeSurfer.csh
-Set up environment or initialize freesurfer (see setenv a lot)
source this script to get your computer ready to use FreeSurfer (sources other scripts & sets other variables)
setenv SUBJECTS_DIR /path/to/data

76. Registration -align subjects -common space
-reference points b/w subjects will be same
transforms
template
deform
morph
warp
compute
resample
computing vs. resampling ie we compute talairach but we don't resample
deform, morph (why it isn't really changing your data)

77. More Help alias e emacs man alias ls file*  lists file1, file2, file3
ls file[12]  lists file1 and file2 but not file3
command >>& file.txt  save output to screen and errors in text file