Common Options for most AFNI Progams

When you master these, you are a long ways towards being an ACE or maybe even a JAM.

'On-the-Fly' Datasets
Most AFNI programs can take as input datasets that are modified in various ways as they are read in. The methods for specifying such datasets are described below.

They all use special characters such as '$ ( ) [ ] < >' which the shell interprets in ways antithetical to AFNI, so you will have to escape these characters on the command line. This is most easily done by putting the entire dataset plus selection list inside forward single quotes, as in 'fred+orig[5..7,9]', or double quotes "x". Double quotes are necessary if you wish to use the '$' character to expand shell variables, as in

   set nlast = 32
   afni elvis+orig"[0..${nlast}]"

Single quotes are necessary if you want to use the '$' character to indicate the last sub-brick in a dataset, and not have '$' trigger an attempted shell variable expansion.

Sub-brick selection
You can add a sub-brick selection list after the end of the dataset name. This allows only a subset of the sub-bricks to be read in (by default, all of a dataset's sub-bricks are input). A sub-brick selection list looks like one of the following forms:
```
   fred+orig[5]                     ==> use only sub-brick #5
   fred+orig[5,9,17]                ==> use #5, #9, and #17
   fred+orig[5..8]     or [5-8]     ==> use #5, #6, #7, and #8
   fred+orig[5..13(2)] or [5-13(2)] ==> use #5, #7, #9, #11, and #13
```
Sub-brick indexes start at 0; for example '[0..20]' refers to 21 sub-bricks, not 20. You can use the character '$' to indicate the last sub-brick in a dataset; for example, you can select every third sub-brick by using the selection list
```
   'fred+orig[0..$(3)]'
```
- N.B.: The sub-bricks are read in the order specified, which may not be the order in the original dataset. For example, using
```
   'fred+orig[0..$(2),1..$(2)]'
```
  will cause the sub-bricks in fred+orig to be input into memory in an interleaved fashion. Using
```
   'fred+orig[$..0]'
```
  will reverse the order of the sub-bricks. (It is hard to conceive of an application for such an ability, but AFNI gives it to you anyway.)
- N.B.: Datasets using sub-brick/sub-range selectors are treated as:
  - 3D+time if the dataset is 3D+time and more than 1 brick is chosen
  - Otherwise, as bucket datasets (-abuc or -fbuc) (in particular, fico, fitt, etc datasets are converted to fbuc!)

Sub-range selection
You may also use the syntax <a..b> after the name of an input dataset to restrict the range of values read in to the numerical values in a..b, inclusive. For example,
```
    'fred+orig[5..7]<100..200>'
```
creates a 3 sub-brick dataset with values less than 100 or greater than 200 from the original set to zero. If you use the <> sub-range selection without the [ ] sub-brick selection, it is the same as if you had put '[0..$]' in front of the sub-range selection.

This capability was mostly intended to allow easy extraction of a sub-mask from a mask dataset containing multiple values, each value corresponding to a distinct anatomical region.

Calculated Datasets
Datasets may also be specified as runtime-generated results from program 3dcalc. This type of dataset specifier is enclosed in quotes, and starts with the string '3dcalc(':
```
    '3dcalc( opt opt ... opt )'
```
where each opt is an option to program 3dcalc (and opt must not be in quotes); this program is run to generate a dataset in the directory given by environment variable TMPDIR (default=/tmp). This dataset is then read into memory, locked in place, and deleted from disk. For example
```
    afni -dset '3dcalc( -a r1+orig -b r2+orig -expr a/b )'
```
will let you look at the ratio of datasets r1+orig and r2+orig, without pre-computing it into a disk file you'll have to delete later.

This option can be particularly useful for computing a mask on-the-fly from a master dataset, as in
```
     3dmaskave -mask '3dcalc( -a stat+orig[3] -b stat+orig[5] -expr step(a-3.3)*step(b-3.3) )' fred+orig
```
N.B.: using this dataset input method can use lots of memory!

Auto-Tcat Datasets
Multiple datasets can be combined in the time dimension by putting spaces between them, with the whole 'dataset name' enclosed in quotes on the command line. For example:
```
     3dTstat 'a+orig b+orig c+orig'
```
will compute the mean of each voxel, across 3 datasets and along the time axis. An alternative way to perform this task would be to create a temporary dataset:
```
     3dTcat -prefix ttt a+orig b+orig c+orig
     3dTstat ttt+orig
     /bin/rm -f ttt+orig.*
```

1D files as AFNI datasets
Most (but not all) AFNI '3d*' programs can operate on 1D files as if they were 3D datasets. This capability is limited to programs that operate on data voxel-wise -- that do not do inter-voxel computations (since no spatial structure is implied by the 1D format). In this usage, each row of a 1D file is a separate "voxel", and each column represents a sub-brick (e.g., time point). Thus, the file below has 3 voxels and 5 time points:
```
   3 7 9 11 12
   2 4 6  8 10
  -1 2 2 -5  7
```
To process a single column 1D file as a time-dependent dataset, the file must be transposed on the command line using the \' notation (see below for details). To experiment with this type of input, one simple test is to use commands like
```
   3dTstat -prefix - '1D: 3 4 5 6 | 2 3 4 5'
   3dTstat -prefix - '1D: 3 4 5 6 | 2 3 4 5'\'
```
where '1D: 3 4 5 6 | 2 3 4 5' is command line shorthand (see the next section) for the file
```
  3 2
  4 3
  5 4
  6 5
```
and '-prefix -' means to write the 1D output to stdout (the screen), which is useful for gaining quick understanding.
- You can't input a 1D 'dataset' to 3dcalc in this way -- that program treats 1D files in a special way. However, the 1deval program is available for doing calculations on 1D files.
- You also can't input a 1D dataset to the interactive afni program this way.
- 3dDeconvolve has a special -input1D option for inputting a single column 1D file as a time series.
- If you set environment variable AFNI_1D_TIME to YES, then when a multicolumn .1D file is read in as an AFNI dataset, the column variable is taken to be time, and a time-dependent dataset is created. (The default is to create a bucket dataset, with no time axis information.) The value of TR can be set via environment variable AFNI_1D_TIME_TR.
N.B.: There is a difference between putting a 1D file in a place where a 3D dataset is expected and putting a 1D file in where a 1D file is expected.
- 1D file in place of a 3D dataset: each row is a separate voxel and time proceeds across the columns.
- 1D file in place of a 1D file: time proceeds down the rows and each column is a separate time series.
The above rules mean that if you want to process a single column of numbers with a '3d*' program, you will usually need to transpose it. For example, if you want to use 3dDetrend to process a 1D column file, then you might do something like so:
```
  setenv AFNI_1D_TRANOUT YES
  3dDetrend -prefix - -vector G1.1D -polort 3 G5.1D\' | 1dplot -stdin
```
where files G1.1D and G5.1D are both 1 column files with the same number of rows (time points). Note that G1.1D is not transposed on input, since it is in a place that 'expects' a 1D file, but that G5.1D is transposed on input with \' since it appears in a place that 'expects' a 3D file.
- Note that setting environment variable AFNI_1D_TRANOUT to YES means that when a 3d* program writes a 'dataset' that is a 1D file, it will transpose it so that the time axis is down the columns, rather than across the columns -- but only if the 'dataset' prefix is '-' (for stdout) or ends in '.1D'.
- I know this transposition stuff is confusing, but remember that suffering is a sign that you are still bound to the wheel of Samsara, as are we all. Om Mane Padme Hum.

Datasets on the Web
It is also possible to read datasets across the Web; for example:

  afni -com 'OPEN_WINDOW axialimage' http://afni.nimh.nih.gov/pub/dist/data/TTatlas.nii.gz

The file(s) are actually fetched to the /tmp directory, then read in from disk, locked into memory (marked as un-purge-able in AFNI), and then the files are deleted from /tmp. You cannot use sub-brick selectors or other modifiers on such datasets.

'On-the-fly' 1D Files
A similar repertoire of methods is available for editing 1D files on the command line.

Column Selection with [ ]
When specifying a timeseries file to an command-line AFNI program, you can select a subset of columns using the '[...]' notation:
```
  'fred.1D[5]'            ==> use only column #5
  'fred.1D[5,9,17]'       ==> use columns #5, #9, and #17
  'fred.1D[5..8]'         ==> use columns #5, #6, #7, and #8
  'fred.1D[5..13(2)]'     ==> use columns #5, #7, #9, #11, and #13
```
Column indices start at 0. You can use the character '$' to indicate the last column in a 1D file; for example, you can select every third column in a 1D file by using the selection list
```
  'fred.1D[0..$(3)]'      ==> use columns #0, #3, #6, #9, ....
```

Row Selection with { }
Similarly, you select a subset of the rows using the '{...}' notation:
```
  'fred.1D{0..$(2)}'      ==> use rows #0, #2, #4, ....
```
You can also use both notations together, as in
```
  'fred.1D[1,3]{1..$(2)}' ==> columns #1 and #3; rows #1, #3, #5, ....
```

Direct Input of Data on the Command Line with '1D:'
You can also input a 1D time series directly on the command line, without an external file. The 'filename' for such input has the general format
```
  '1D:n_1@val_1,n_2@val_2,n_3@val_3,...'
```
where each 'n_i@' is an integer repetition count (which can be omitted) and each 'val_i' is a float value. For example
```
   '1D:5@0,10.0,5@0,10.0'
```
which specifies a single 'column' comprising 5+1+5+1=12 numbers.
- Spaces or commas can be used to separate values.
- A '|' character can be used to start a new input "line"; for example
```
   1dplot -DAFNI_1DPLOT_THIK=0.01 -one '1D: 3 4 3 5 | 3 5 4 3'
```
  which should plot 2 curves: 1 from each 'column' of 4 values.
It is also possible to format the output of program 1deval so that it can be captured on the command line for interactive use. For example:
```
  1dplot `1deval -1D: -num 71 -expr 'cos(t/2)*exp(-t/19)'`
```
Here, the '-1D:' option tells the program to format the output starting with the string '1D:' and to separate numbers with commas instead of spaces or newlines. The usual shell backquotes `...` captures the output of the 1deval command to the command line, and that becomes the input to program 1dplot. (If you want to see what the '1deval -1D:' output looks like, just run the command itself without the backquotes or the 1dplot.)

Transposition with \'
You can force most AFNI programs to tranpose (i.e., swap rows for columns) a 1D file on input by appending a single ' character at the end of the filename. Since the ' character is also special to the shell, you'll probably have to put a \ character before it. Contrast the results of these two commands:
```
       1dplot '1D: 3 2 3 4 | 2 3 4 3'      and
       1dplot '1D: 3 2 3 4 | 2 3 4 3'\'
```

-Dname=val
Sets environment variable 'name' to 'val'.
Some AFNI program features can only be controlled from outside by setting environment variables. For example:
1dplot -DAFNI_1DPLOT_COLOR_01=rgbi:0/1/0 -DAFNI_1DPLOT_THIK=.01 '1D: 3 4 5 3 2 1'
creates a graph with the default line color changed from black to green and also makes the lines very thick.
For details about AFNI environment variables, see http://afni.nimh.nih.gov/pub/dist/doc/program_help/README.environment.html

-overwrite
Allows 3D datasets to be overwritten.
Most AFNI programs will not destroy existing datasets; this option tells them that it is OK to write over an existing dataset file if necessary.

-skip_afnirc
Skips the processing of your ~/.afnirc file.
This file, if present, can be used to set environment variables to affect AFNI programs. Sometimes you might want to run an AFNI program and not have your settings applied; this option provides an easy way to skip such settings.