.. _U_basic_4: ******************************* 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. Commands and descriptions: - :ref:`single quotes ` - :ref:`double quotes ` - :ref:`backslash characters ` - :ref:`pound characters ` - :ref:`U_mc_cat` : display a text file in the terminal window - :ref:`U_mc_gedit` : a graphical editor - `3dDeconvolve -help `_ 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. 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_regress Alternatively, it would be fine to open the text file in an editor:: gedit rall_regress & The output (ignoring gedit) should look like this: .. image:: media/basic_4_A.jpg :align: center 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). 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 2 The ``\`` 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: .. image:: media/basic_4_B.jpg :align: center The commands are identical, but this unindented version is far more difficult to read. .. seealso:: Unix error message: :ref:`U_MU_err_cmd_not_found` - section: incorrect use of ``\`` characters 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. .. seealso:: `3dDeconvolve -help `_ .. _U_basic_4_quotes: 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]" Use of comments --------------- Another short script can be seen in the file :file:`epi_r1_regress`. This script contains 2 AFNI commands, along with comments describing those commands. View the script using:: cat epi_r1_regress .. image:: media/basic_4_C.jpg :align: center 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 what ``3dvolreg`` is, 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 ``3dDeconvolve`` command 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).