AFNI program: 1deval

Usage: 1deval [options] -expr 'expression'
Evaluates an expression that may include columns of data
from one or more text files and writes the result to stdout.

* Any single letter from a-z can be used as the independent
   variable in the expression. Only a single column can be
   used for each variable.
* Unless specified using the '[]' notation (cf. 1dplot -help),
   only the first column of an input 1D file is used, and other
   columns are ignored.
* Only one column of output will be produced -- if you want to
   calculate a multi-column output file, you'll have to run 1deval
   separately for each column, and then glue the results together
   using program 1dcat.  [However, see the 1dcat example combined
   with the '-1D:' option, infra.]

Options:
--------
  -del d   = Use 'd' as the step for a single undetermined variable
               in the expression [default = 1.0]
  -start z = Start at value 'z' for a single undetermined variable
               in the expression [default = 0.0]
  -num n   = Evaluate the expression 'n' times.
               If -num is not used, then the length of an
               input time series is used.  If there are no
               time series input, then -num is required.
  -a q.1D  = Read time series file q.1D and assign it
               to the symbol 'a' (as in 3dcalc).
  -index i.1D = Read index column from file i.1D and
                 write it out as 1st column of output.
                 This option is useful when working with
                 surface data.
  -1D:     = Write output in the form of a single '1D:'
               string suitable for input on the command
               line of another program.
               [-1D: is incompatible with the -index option!]
Examples:
---------
 1deval -expr 'sin(2*PI*t)' -del 0.01 -num 101 > sin.1D
 1deval -expr 'a*b' -a fred.1D -b ethel.1D > ab.1D
 1deval -start 10 -num 90 -expr 'fift_p2t(0.001,n,2*n)' | 1dplot -xzero 10 -stdin
 1deval -x '1D: 1 4 9 16' -expr 'sqrt(x)'

Examples using '-1D:' as the output format:
-------------------------------------------
 1dplot `1deval -1D: -num 71 -expr 'cos(t/2)*exp(-t/19)'`
 1dcat `1deval -1D: -num 100 -expr 'cos(t/5)'` \
       `1deval -1D: -num 100 -expr 'sin(t/5)'` > sincos.1D
 3dTfitter -quiet -prefix -                                     \
           -RHS `1deval -1D: -num 30 -expr 'cos(t)*exp(-t/7)'`  \
           -LHS `1deval -1D: -num 30 -expr 'cos(t)'`            \
                `1deval -1D: -num 30 -expr 'sin(t)'`              

Notes:
------
* Program 3dcalc operates on 3D and 3D+time datasets in a similar way.
* Program ccalc can be used to evaluate a single numeric expression.
* If I had any sense, THIS program would have been called 1dcalc!
* For generic 1D file usage help, see '1dplot -help'
* For help with expression format, see '3dcalc -help', or type
   'help' when using ccalc in interactive mode.
* 1deval only produces a single column of output.  3dcalc can be
   tricked into doing multi-column 1D format output by treating
   a 1D file as a 3D dataset and auto-transposing it with \'
   For example:
     3dcalc -a '1D: 3 4 5 | 1 2 3'\' -expr 'cbrt(a)' -prefix -
   The input has 2 'columns' and so does the output.
   Note that the 1D 'file' is transposed on input to 3dcalc!
   This is essential, or 3dcalc will not treat the 1D file as
   a dataset, and the results will be very different.

-- RW Cox --

++ Compile date = Jul 24 2008