5. Basic Unix : special characters¶
This section covers two of the common special characters one might encounter in a shell script, the single quote and backslash characters.
Starting from the AFNI_data6/afni directory, look at the contents
of one of the other text files. The file rall_regress is a text
file with a single command in it.
The program that would get run from the script (which we will not do
here) is 3dDeconvolve, an AFNI program to use linear
regression to fit a model against time series data. Understanding the
command from an AFNI perspective is outside the scope of this
Unix tutorial.
The goal here is to understand this script from a Unix perspective.
5.1. Look at the script¶
Display the contents of rall_regress, either in the terminal
window or in an editor. The script is under AFNI_data6/afni, in
case you are not already there.
commands (type these in the terminal window):
cd ~/AFNI_data6/afni cat rall_regressAlternatively, it would be fine to open the text file in an editor:
gedit rall_regress &The output (ignoring gedit) should look like this:
5.2. Command overview¶
The file rall_regress contains a single AFNI command,
3dDeconvolve.
The command is used to model aligned EPI data via linear regression, where the model is specified by the user (via 3dDeconvolve options and stimulus timing files).
For the purposes of this tutorial, we do not particularly care to
evaluate this command from an AFNI perspective. However, the
command parameters and options must be in the format expected by
3dDeconvolve, so some mention will be made.
For example, it is important to know that the -concat option takes
only 1 parameter. Since we want to pass 1D: 0 150 300 as that
single parameter (and not as 4 parameters), special shell characters
will be applied (those terms are surrounded by quotes, just to group
them into a single parameter).
5.3. Backslash characters (\)¶
The file rall_regress (which was viewed using gedit, just above)
is a simple script with one 3dDeconvolve command in it.
This is actually one long command. A
\character (when it is the very last character on a line, including spaces and tabs) tells the shell that the current command continues on the following line. Repeating that notion shows that this is one long command (abbreviated by):3dDeconvolve -input rall_vr+orig ... -bucket rall_func -jobs 2The
\characters are not required, they are only there to make the file more readable. The\characters, along with use of indentation to align similar options over successive lines, greatly affect the time it takes to visually parse and understand the command. Without\and indentation, the command might look like:
The commands are identical, but this unindented version is far more difficult to read.
5.4. Option parameter grouping¶
Command options (generally) start with ‘-’ and are followed by zero or more parameters.
For example, the -num_stimts option takes 1 parameter (the number of stimulus timing files to be specified), and in this case 8 is specified. Note the subsequent 8 script lines describing timing and stimulus files.
Alternatively, the -stim_times option takes 3 parameters (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 implies is saved for a class on 3dDeconvolve.
See also
5.5. Use of quotes¶
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 (so that 3dDeconvolve knows the ‘roll’ regressor comes from column #0 of motion.1D). 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]'The quotes could go in multiple places, as they are just used to hide []. Plus, either single or double quotes would hide those characters from the shell, so the following example would work as well:
-stim_file 3 "motion.1D[0]"
5.6. Use of comments¶
Another short script can be seen in the file epi_r1_regress.
This script contains 2 AFNI commands, along with comments describing those commands. View the script using:
cat epi_r1_regress
A
#character (that is not hidden from the shell using quotes, say) is ignored by the shell, along with the rest of that line, as if it were not in the script. The purpose of such a “comment line” is to describe the script’s intention to someone reading it. So even with out knowing what3dvolregis, we can read that it will register the time series dataset, saving the motion parameters (to a file, presumably).The next comment suggests that the
3dDeconvolvecommand is used to perform a simple regression on the newly registered data. It is very similar to the rall_regress script, reviewed above.
Note
The ‘cat’ command is only useful for short files. For longer files, ‘less’ is much more useful (‘less’ will be covered elsewhere).
