Scripting Basics

A script is a file containing commands. Executing the script is exactly the same as typing the commands at the shell prompt ("$"). Usually these commands contain variables in place of actual arguments to the commands, so you can execute exactly the same sequence of commands with different arguments, for example dataset names.

We'll get to more detailed examples in a moment. First of all we need to say what an executable script actually is, and how to create one. A script is just a text file, that has been made executable. To make a file executable, use the Unix command chmod, as follows:

chmod +x filename

You'll need to do this with scripts that you download from the website. For example, the parsemarks script. When you download it, it'll just be a text file. By making it executable, it will become a command that you can use at the shell (or command) prompt.

Note that scripts may be written in any of several different languages. The first line of any script specifies which language to use. For example, the first line of the parsemarks script is:

#! /usr/bin/env python

which means that it is a Python script. Most of the scripts that you will write, however, will be shell scripts. The shell is the Unix command interpreter; in other words, it's the program that prints the "$" prompt, and takes care of actually running all the commands that you type. The first line of a shell script is:

#! /bin/bash

or

#! /bin/sh

/bin/sh is the location (the actual filename) of the shell. On most Linux systems, bash and sh are synonyms.

There are other shells available besides bash; type

$ echo $SHELL

to see which one you are using.

Installing scripts

Most of the scripts you write will stay in whatever directory you're working in, so you don't need to do anything. Some scripts (like parsemarks) and also programs (like brainhull) are more general purpose, and will go into your bin directory. If you don't have one, you can create it like this:

$ cd
$ mkdir bin

The shell also maintains a list of directories called the path that is searched whenever you try to run a command. You want to make sure your bin directory is in your path. Do this:

$ echo $PATH

If you see /home/youruserid/bin, then you're done. Otherwise you'll have to add a line to your login profile (usually the file .bash_profile like this:

$ PATH=${PATH}:/home/youruserid/bin

where youruserid is replaced by your userid (your login name).

If you are using bash as your shell, it will automatically notice when you put something into your bin directory, but if you are using the "t-shell" tcsh, you'll have to tell it using the command rehash. The command for setting the path is a little different too.

% setenv PATH ${PATH}:~/bin 
% mv parsemarks ~/bin 
% rehash 

The ~ character is a synonym for your home directory (works in bash, too). The setenv command would go in your .tcshrc or .login file.

A Simple Script

Let's say the following text is placed in the file "moo":

#! /bin/bash

# This is a comment.

echo There are "$#" arguments, and the first two are "$1" and "$2".

After you say "chmod +x moo", the file moo will become a command, so you can do this:

$ moo this is a test
There are 4 arguments, and the first two are this and is.

In any shell script, "$#" is replaced with the number of arguments, and "$1", "$2", etc., are replaced with the first, second, etc. arguments.

A Less Simple Script

Let's say you have several datasets, and you wish to perform the same operations on all of them. To be concrete, let's assume you want to make an average of the region around a stimulus, specified by the marker "stim". Here's a script, called doavg, that does one dataset.

#! /bin/sh

test "$#" -ne 1 && echo usage: $0 dataset && exit 1

ds="$1"
dir=`dirname $ds`
name=`basename $ds .ds`

newds="$dir/${name}-avg.ds"

averageDs -marker stim -time -.3 .7 $ds $newds

There are several things to note about this script. First of all, it checks the number of arguments ("$#") and prints a usage message if it isn't 1. Next, the first argument is assigned to the variable "$ds", which just makes it easier to remember what it is. Second, anything in backquotes ("`"), is executed as a command, and the result is substituted in its place. The result of the command "dirname $ds" is the directory portion of the argument, and similarly the basename command returns just the filename part with the extension stripped off (here, ".ds"). So, if you say:

$ doavg /data/expt/subjA.ds

then the variable $dir will contain "/data/expt", and $name will be "subjA".

Thirdly, variable names can contain letters, numbers, and some punctuation. It's not always clear where a variable begins or ends, so the syntax "${name}" is used to be clear; this would be especially important if you were numbering things, for example, and tried to say "$name1", where what you meant was "${name}1". Watch out for that.

The above doavg command will thus create the dataset "/data/expt/subjA-avg.ds". To run this same command on all your subjects, you could create another script, called "dodoavg" that contains this:

#! /bin/sh

# usage: dodoavg

for s in subj1 subj2 subj3 subj4; do
    doavg /data/expt/${s}.ds
done

This is a loop, and the variable "$s" will be substituted with each subject name in turn. Note that doavg is just a command like any other (assuming you have done "chmod +x doavg"!).

Protecting Your Data

It sometimes happens that one types an unfortunate command, such as "rm -rf data" or similar. In order to guard against this and other disasters, there are some easy things you can do to protect yourself.

• Use different user ids. If you have a dataset that is really read-only and shouldn't be messed with, create a separate user id for it and keep it where nobody can find it.
• Make regular backups of everything.
• Make DVD copies of your datasets and scripts.
• Make regular backups.
• Use file protection. Keep all your data in a directory called "data" and remove write permission from that tree:

chmod -R -w data

Even the command "rm -rf data" will fail if you do this, unless you are superuser. Later you can reverse that with:

chmod -R +w data

if you want to change something.

• Make regular backups. And keep copies of everything. Commands for making copies (don't forget your scripts):

cp -a datasrc datadst
tar -cjvf archive.tar.bz2 data
scp -r data user@host:/remote_data1/moo
cp -a scripts scripts_backup

Again, as a reminder, we might not have a copy of your data if you accidentally lose your copy(s). In any case we won't have your scripts, or the marked and processed data, or the MRIs. You should keep multiple copies of things, and/or make hard backups on DVD or tape. Disk space is cheap enough these days that you can just keep several copies of everything.