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

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.

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.

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.

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

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

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

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 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 cal

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.

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

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

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

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

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

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

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

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

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”

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

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

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

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

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

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

/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!

Changing Directories

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

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

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

Using an Editor

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

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

/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

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 ..

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

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

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

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

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

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

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

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)

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

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

More Help http://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/CommandLineNavigation Links on Wiki under “Unix Tutorial” Glossary of Unix commands

The End Good Luck!

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

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)

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)

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

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

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

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

Recon

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

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

Cortical vs. Subcortical GM -subcortical masked out sagittal coronal

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

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

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

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

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

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

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

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

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

before spatial alignment after spatial alignment

before spatial alignment after spatial alignment

Inter-subject non-linear example target CVS reg

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

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

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

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

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

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)

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