Unix Tutorial

Who this tutorial is for:

People with little to no Unix experience, or with some experience but looking for a refresher.

What are the goals of this tutorial:

To let the student practice the Unix skills and concepts needed to enjoy this course. The skills include:

What is a Unix terminal?

A terminal is a way for you to interact with your computer - just like you interact with your phone through the touch screen or your laptop through the track pad. The terminal lets you interact with your computer through typed in commands.

Why learn about Unix terminals?

Throughout this course you will be using the Unix terminal to interact with FreeSurfer and access data. Many computer programs for scientific use are designed to be operated through the terminal. By the end of this tutorial you will have familiarity with finding data and launching programs through the terminal.

How do I use the terminal?

Getting Started

TerminalIcon.png Click the terminal icon on the left side of your screen to launch the terminal.

A window will pop open on the screen, before we start typing into it it would be good to adjust the window to be easier to work with. Right click on the bar on the top of the window, then select the "Always On Top" option. That will keep the window in view while you navigate this tutorial. You can also move the window by holding left click on that top bar and moving the window, or resize it by holding left click on the corners.

OnTopCropped.png

Whenever you launch the terminal, you can imagine it as if you are getting onto a bike. A bike has a location, and can travel to other locations. The terminal also has a location, and you can navigate it to other locations.

To see where you are, type in  pwd  and press enter. The terminal will print out where you are, locations in Unix are called "directories". pwd is short for "Print Working Directory", it prints out where you are. This is like asking your GPS "Where am I?".

pwd.png

Looking at files

To see what data is in this directory, type in  ls  and press enter.

You will see a list of 2 different things:

folders.png

files.png

You will use  ls  a lot to take a look at where to go next while navigating the terminal, I probably use ls 100s of times a day!

You find data in the Unix terminal by looking through directories, all data belongs inside a directory somewhere on the computer. If you use Windows or OSX you might know the term "folder", directories are the same concept.

One of the directories you can go to now is called  tutorial_data  lets enter that directory and explore what is inside.

Type  cd tutorial_data  and press enter

Now we are in the tutorial_data directory, try two things to explore:

  1. Type in  ls  to see what is in this directory

  2. Type in pwd to see what our working directory is now

Enter the practice_with_data directory with  cd practice_with_data 

Enter ls to see whats inside. There should be 2 directories. Enter the dicoms directory now, try to do it on your own, but look below if you need help.

Want to know the answer? Click and drag to highlight and reveal the text below.

cd dicoms

Once inside dicoms, enter a command to see what data is inside. Try to do it on your own, but look below if you need help.

Want to know the answer? Click and drag to highlight and reveal the text below.

ls

What you see is a list of data taken from a scan session, FreeSurfer takes this data and turns it into a whole lot of useful new data like 3d surfaces of brains. Let's take a look at some of that FreeSurfer data, first, leave the dicoms directory. How do you do that? Type in  cd .. 

 cd ..  will take you out of the directory you are in, and into the directory that directory is in. Type ls again to see where you can go, then go into the Subj001 directory. Hint: Capitalization matters!

Type ls to see whats inside the Subj001 directory - you are looking at a bunch of directories made by FreeSurfer to organize processed subject data. You will spend time during this course learning what all of this data means. Spend some time now exploring these directories with  cd   ls  and  cd .. 

Getting around quicker

Because you've spent some time exploring on your own, let's get you back to a particular spot. Type in  cd ~  (Hint, the ~ is the key to the left of the number 1 and q keys ). That will take you back to the directory we started in when you first opened the terminal. Take a look at the files in that directory again.

Now type in only  cd tu  and don't press enter.

pretab.png

Press tab and the terminal will fill in what it thinks you will type - kind of like autocomplete on your phone or browser. It should fill it in with  tutorial_data/  , now enter the directory.

posttab.png

Enter  ls  again, and the terminal will show you everything in the  tutorial_data  directory, start adding cd practice_data , but press tab again a few characters in to auto-complete it and enter the directory. Now type in S and press tab to autocomplete that, then press m and press tab to autocomplete  mri . You should have   cd tutorial_data/practice_with_data/Subj001/mri/  as your command, press enter to enter that directory.

Take a look at the files inside, these are freesurfer volumes. You will learn more about these later - but for now lets examine one.

Launching programs

Usually you can only access files and programs inside the directory the terminal is in - but we set up your computer so that you can launch FreeView (a tool to look at FreeSurfer data) anywhere. Enter this command to launch FreeView and examine some data

 freeview -v orig.mgz 

Usually, after you type in a program name, you add something called arguments at the end like  -v orig.mgz . In this case the argument opened the orig.mgz volume. Close your FreeView window (click the red X in the upper left hand corner), go back to your terminal, and open the rawavg.mgz volume with FreeView. Look at the command you tried before to see how. When you have done that close FreeView.

Now, an important experiment for you to try. Leave the directory you are in by typing  cd .. }} . Now, try to open the first volume we opened by typing in {{{ freeview -v orig.mgz  . You will get an error! That is expected. The error is because there is no orig.mgz in the directory you are in, the orig.mgz is in a different directory. Orig.mgz is actually in the mri/ directory inside the directory we are in right now, there are 2 different ways we can open it again.

Were you successful? There are a couple of different ways to have done it:

There are often many ways to accomplish anything with the Unix Terminal, so if you ever see something done in a way you don't understand that is okay! The terminal is something you never stop learning about.

Accessing Variables

Moving in and out of directories can be exhausting! What if there was a way to tell your terminal to remember certain directories - like bookmarks in your web browser? There is. You can store directories in variables. Let's use a variable we already set up for you.

type in  cd $TUTORIAL_DATA  (hint, you can use the tab auto-complete here!)

You are back in your tutorial data directory! You can use this if you ever get lost in all of your directories. If you ever just want to take a peek to see what is inside a variable you can use  echo  type in  echo $TUTORIAL_DATA  to see that the variable is holding the path to your tutorial data directory. And if you type in  pwd  you will see that they match, because you are in the tutorial data now!

Whenever you open your terminal, we have it set up so a bunch of handy variables are set up for you. You can close your terminal now and re-open it to see, or just look at the screenshot below:

At the start of most tutorials you will be asked to set the SUBJECTS_DIR variable. FreeSurfer checks the SUBJECTS_DIR to find data, so we change that variable to point to whatever directory has the subject data we want FreeSurfer to process.

Searching for files

Quickly peeking at files

Copying and pasting

Other useful info

Have extra time? Play some Terminus!

http://web.mit.edu/mprat/Public/web/Terminus/Web/main.html

_

There are different ways to mark the location of objects in the world. Lattitude, Longitude, addresses, landmarks, etc. Locations in the terminal are marked through directories.

It will help if you right click the top of the window then choose always on top.

When you open a terminal it usually takes you to your home directory. Type this into the terminal then press enter

Ls

The terminal now lists everything in your home directory. You will see a bunch of folders with different names like “Photos” “Documents”. One of them is “freesurfer” Lets navigate into that folder. Type

Cd freesurfer

And press enter.

Then type ls in again and look at what you see. These are some of the files and folders that make up Freesurfer. There is a lot more to FreeSurfer than just this, inside of those folders ar emore files and folders, and so on and so on. Lets examine the data in one of these files. If you look through the files listed in ls there is one called README, you can peek inside by typing

less README

Press q to leave

Less is a tool in unix that lets you quickly take a peek at files.

Not lets leave the freesurfer directory, you can exit a directory by typing cd.. Do that now

Now lets navigate to the data you will using thorughout the week, type in

Cd $TUTORIAL_DATA

Cd lets you change directories, and $TUTORIAL_DATA is a variable we set up earlier which is the directory of all the data you will use in the tutorial. You can take a peek inside what $TUTORIAL_DATA is representing by typing

Echo $TUTORIAL_DATA

You will see the address of the tutorial data. Echo doesn’t actually make any changes or move where you are - echo just prints out whatever comes after it.

Lets look at some data, type in cd practice_with_data

Type cd dicoms

Type ls

This is is a list of discoms taken from an mri scan - you will learn more about this data in a future tutorial.

Navigate out of that directory, with cd ..

Then cd into Subj001

Type ls, the list of directories you see is a typical set of directories created by freesurfer after it runs a set of data through its pipeline.

We are not going to take a look at some of this data with FreeView!

Type in

Freeview -v orig.mgz

This is an example of an argument. The creators of FreeView haad to decide a way to let the user choose what kind of file they want to open, and which of that file to open. -v means you want to open a volume, and the name of te volume is orig.mgz

Now there are some tricky things here. For example you types in freeview… but there was no Freeview in that directory! So where did it come from? Before you came to class we set up something called a Path, which is a list of directories Unix will search in whenever you launch a command. So, Freeview is in the path, so Freeview was found even though it wasnt in your current directory. NOTE: Allow user to experiment with this. Orig.mgz was in that directory, so it was found. Close Freeview with the x in the upper right hand corner. Now try something.

Navigate up one directory by typiong in cd..

Type ls to see what is in there

Now type Freeview -v orig.mgz just lke before

You will get an error that the file was not found! That is because orig.mgz was not in the directory you are in. Here is what would have worked, feel free to try.

Freeview -v mri/orig.mgz

A volume is one type of data you use in freesurfer, a surface is anohter. Lets open a surface.

Enter the tutorial_data folder again, either by doing the cd.. Comand a couple of types or typing in cd $TUTORIAL_DATA

Cd bucker_data

Cd tutorial_subjs

Cd good_output

Cd surf

You also could have accessed that by typiong cd $TUTORIAL_DATA/buckner_data/tutorial_subjs/good_output/surf but I prefer to go dir by dir.

Type ls and look at allk that data!

Lets open one

Freeview -f lh.pial rh.pial -viewport 3d

-f lets us open surfaces, and -viewport lets us choose what kind of view we want to take. You will get more familiar with these commands as the course goes on.