    Basic Unix 3. (very) Light introduction to shell scripts

       Commands and descriptions:

            cat  : display the contents of a file (usually a short text file)

       help for cat

       What are shell scripts?

            A shell script is a simple text file that contains commands in some
            shell language, e.g. bash, tcsh, python, matlab.  Our focus is on Unix
            and AFNI commands using tcsh syntax (though the syntax used in this
            particular tutorial page could apply to either bash or tcsh).

            A shell script could be typed directly into a terminal window, but is
            written into a text file so that it can be edited, executed multiple
            times, and saved as a history of processing.  For these reasons, using
            shell scripts for data processing is highly recommended.

       A. Move into the AFNI_data6/afni director and see what is there.

             cd AFNI_data6/afni
             pwd
             ls

          There are anatomical, EPI, statistical and mask datasets here, along
          with scripts (text files of commands, such as rall_regress) and stimulus
          timing files (text files of times in seconds, such as stim_AV1_vis.txt).

       D. Look at the contents of some of the text files.  Enter one command at a
          time and note the result.  What follows is meant to provide understanding
          of the contents of each file.

             cat stim_AV1_vis.txt
             cat rall_regress
             cat quick.s1.afni_proc

          file stim_AV1_vis.txt:

             This is not a script, but rather is a stimulus timing file.  But that
             is worth explaining, so...

             The timing file stim_AV1_vis.txt has 3 rows of real numbers, which are
             onset times for stimulus events across 3 runs.  The first 60 means the
             visual stimulus class (AV1_vis) had its first event 60.0 seconds into
             the first run.  In the third run, that stimulus was given at the very
             beginning of the run, at time 0.

          file rall_regress:

             The file rall_regress contains a single AFNI command, 3dDeconvolve.
             The command is used to model the EPI data via linear regression, where
             the model is specified by the user (specified via 3dDeconvolve options
             and stimulus timing files).

             From the Unix perspective, there are a few key points to make.

                1. This is actually 1 long command.  A '\' character (when it is
                   the very last character on a line) tells the shell that the
                   current command continues on the following line.  So

                      3dDeconvolve -input ... -bucket rall_fun -jobs 2

                   is considered one command.

                2. As usual, command options start with '-' and are followed by
                   zero or more parameters.  For example, the -num_stimts option
                   takes one parameter (the number of stimulus timing files to be
                   specified), and in this case 8 is specified.  Note that the
                   subsequent 8 lines describe those timing files.

                   Alternatively, the -stim_times option takes 3 paramters (the
                   stimulus index, the name of the timing file, and the basis
                   function).  But our focus is on the Unix aspect, so we just note
                   that the option and parameter grouping is:

                      -stim_times 1 stim_AV1_vis.txt 'BLOCK(20,1)'

                   What that option means is saved for a class on 3dDeconvolve.
                   See the output from "3dDeconvolve -help" for details.

                3. Quotes are used for multiple reasons in this one command.
                   The quotes around '1D: 0 150 300' have the shell pass that text
                   as a single parameter, instead of as 4.  So 3dDeconvolve sees
                   "-concat" as one parameter, and then "1D: 0 150 300" as the next.
                   It does NOT see -concat then 1D: then 0 then 150 then 300.

                   Quotes are used again this way with the -gltsym option.

                   Another way to view this is that the quotes hide the spaces from
                   from the shell, so that they are not processed as parameter
                   separation characters.  Which leads us to the other use of the
                   quotes here...

                   The stim_times option takes a basis function as its third
                   parameter, e.g. 'BLOCK(20,1)'.  But the () characters are
                   special to the shell.  So to hide those characters from the
                   shell and let 3dDeconvolve see them, they are put within quotes.
                   That way 3dDeconvolve reads BLOCK(20,1) as the basis function.

                   Similarly, [] are special to the shell (for wildcard matching).
                   But we want to pass motion.1D[0] to 3dDeconvolve (using the
                   -stim_file option).  And to prevent the shell from trying to use
                   [0] for wildcard file name matching, it is put in quotes, as in:

                      -stim_file 3 motion.1D'[0]'

                   Note that the quotes could go in multiple places, they are used
                   to hide [].  So the following would work as well:

                      -stim_file 3 'motion.1D[0]'

          file quick.s1.afni_proc:

             Like rall_regress, this file contains a script with just one command.
             The afni_proc.py command is used to generate a single subject FMRI
             processing script, and in this case, execute it.

             This script has line continuation characters '\' as before, as well
             as single quotes hiding special charcters from the shell in the option
             -regress_basis 'BLOCK(20,1)'.

             From a Unix perspective, the additional aspect of this script is the
             pound/sharp character '#'.  When used in a script, this character says
             that the rest of the line is to be ignored.  Effectively, the script
             does not see anything from '#' to the end of the line.

             Such lines are generally used as comment lines, a way to tell/remind
             the reader the purpose of the following line or lines in the script.

             In this example, the comment describes what the afni_proc.py command
             will end up doing (creating and then executing a processing script).

    Comment(s):

        1. The 'cat' command is only useful for short files.  For longer files,
           'less' is much more useful ('less' will be covered in another tutorial).