NAME

       gmtmath - Reverse Polish Notation calculator for data tables


SYNOPSIS

       gmtmath [ -At_f(t).d ] [ -Ccols ] [ -Hnrec ] [ -Nn_col/t_col ] [ -Q ]
        [  -S[f|l]  ][  -Tt_min/t_max/t_inc|tfile  ]  [  -V  ] [ -bi[s][n] ] [
       -bo[s][n] ] operand [ operand ] OPERATOR [ operand ] OPERATOR ...  =  [
       outfile ]


DESCRIPTION

       gmtmath  will  perform  operations  like  add,  subtract, multiply, and
       divide on one or more table data files or constants using Reverse  Pol-
       ish  Notation  (RPN)  syntax  (e.g., Hewlett-Packard calculator-style).
       Arbitrarily complicated expressions may  therefore  be  evaluated;  the
       final  result  is  written to an output file [or standard output]. When
       two data tables are on the stack, each element in file A is modified by
       the  corresponding  element  in  file  B.  However, some operators only
       require one operand (see below). If no data  tables  are  used  in  the
       expression  then  options  -T,  -N  must be set (and optionally -b). By
       default, all columns except the "time" column are operated on, but this
       can be changed (see -C).

       operand
              If  operand  can be opened as a file it will be read as an ASCII
              (or binary, see -bi) table data file.  If  not  a  file,  it  is
              interpreted  as  a  numerical  constant or a special symbol (see
              below).

       outfile is a table data file that will hold the final  result.  If  not
       given then
              the output is sent to stdout.

       OPERATORS
              Choose among the following operators:
              Operator n_args Returns

              ABS 1 abs (A).
              ACOS 1 acos (A).
              ACOSH 1 acosh (A).
              ADD(+) 2 A + B.
              AND 2 NaN if A and B == NaN, B if A == NaN, else A.
              ASIN 1 asin (A).
              ASINH 1 asinh (A).
              ATAN 1 atan (A).
              ATAN2 2 atan2 (A, B).
              ATANH 1 atanh (A).
              BEI 1 bei (A).
              BER 1 ber (A).
              CEIL 1 ceil (A) (smallest integer >= A).
              CHICRIT 2  Critical  value  for  chi-squared-distribution,  with
              alpha = A and n = B.
              CHIDIST  2 chi-squared-distribution P(chi2,n), with chi2 = A and
              n = B.
              COL 1 Places column A on the stack.
              COS 1 cos (A) (A in radians).
              COSD 1 cos (A) (A in degrees).
              COSH 1 cosh (A).
              D2DT2 1 d^2(A)/dt^2 2nd derivative.
              D2R 1 Converts Degrees to Radians.
              DILOG 1 dilog (A).
              DIV(/) 2 A / B.
              DDT 1 d(A)/dt 1st derivative.
              DUP 1 Places duplicate of A on the stack.
              ERF 1 Error function erf (A).
              ERFC 1 Complementary Error function erfc (A).
              ERFINV 1 Inverse error function of A.
              EQ 2 1 if A == B, else 0.
              EXCH 2 Exchanges A and B on the stack.
              EXP 1 exp (A).
              FCRIT 3 Critical value for F-distribution, with alpha = A, n1  =
              B, and n2 = C.
              FDIST  3 F-distribution Q(F,n1,n2), with F = A, n1 = B, and n2 =
              C.
              FLIPUD 1 Reverse order of each column
              FLOOR 1 floor (A) (greatest integer <= A).
              FMOD 2 A % B (remainder).
              GE 2 1 if A >= B, else 0.
              GT 2 1 if A > B, else 0.
              HYPOT 2 hypot (A, B) = sqrt (A*A + B*B).
              I0 1 Modified Bessel function of A (1st kind, order 0).
              I1 1 Modified Bessel function of A (1st kind, order 1).
              IN 2 Modified Bessel function of A (1st kind, order B).
              INT 1 Numerically integrate A.
              INV 1 1 / A.
              ISNAN 1 1 if A == NaN, else 0.
              J0 1 Bessel function of A (1st kind, order 0).
              J1 1 Bessel function of A (1st kind, order 1).
              JN 2 Bessel function of A (1st kind, order B).
              K0 1 Modified Kelvin function of A (2nd kind, order 0).
              K1 1 Modified Bessel function of A (2nd kind, order 1).
              KN 2 Modified Bessel function of A (2nd kind, order B).
              KEI 1 kei (A).
              KER 1 ker (A).
              LE 2 1 if A <= B, else 0.
              LMSSCL 1 LMS scale estimate (LMS STD) of A.
              LOG 1 log (A) (natural log).
              LOG10 1 log10 (A) (base 10).
              LOG1P 1 log (1+A) (accurate for small A).
              LOG2 1 log2 (A) (base 2).
              LOWER 1 The lowest (minimum) value of A.
              LRAND 2 Laplace random noise with mean A and std. deviation B.
              LSQFIT 1 Let current table be [A  |  b];  return  least  squares
              solution x = A \ b.
              LT 2 1 if A < B, else 0.
              MAD 1 Median Absolute Deviation (L1 STD) of A.
              MAX 2 Maximum of A and B.
              MEAN 1 Mean value of A.
              MED 1 Median value of A.
              MIN 2 Minimum of A and B.
              MODE 1 Mode value (Least Median of Squares) of A.
              MUL(x) 2 A * B.
              NAN 2 NaN if A == B, else A.
              NEG 1 -A.
              NEQ 2 1 if A != B, else 0.
              NRAND  2 Normal, random values with mean A and std. deviation B.
              OR 2 NaN if A or B == NaN, else A.
              PLM 3 Associated Legendre polynomial P(-1<A<+1) degree  B  order
              C.
              POP 1 Delete top element from the stack.
              POW(^) 2 A ^ B.
              R2 2 R2 = A^2 + B^2.
              R2D 1 Convert Radians to Degrees.
              RAND 2 Uniform random values between A and B.
              RINT 1 rint (A) (nearest integer).
              ROOTS 2 Treats col A as f(t) = 0 and returns its roots
              ROTT 2 Rotate A by the (constant) shift B in the t-direction.
              SIGN 1 sign (+1 or -1) of A.
              SIN 1 sin (A) (A in radians).
              SINC 1 sinc (A) (sin (pi*A)/(pi*A)).
              SIND 1 sin (A) (A in degrees).
              SINH 1 sinh (A).
              SQRT 1 sqrt (A).
              STD 1 Standard deviation of A.
              STEP 1 Heaviside step function H(A).
              STEPT 1 Heaviside step function H(t-A).
              SUB(-) 2 A - B.
              SUM 1 Cumulative sum of A
              TAN 1 tan (A) (A in radians).
              TAND 1 tan (A) (A in degrees).
              TANH 1 tanh (A).
              TCRIT  2 Critical value for Student’s t-distribution, with alpha
              = A and n = B.
              TDIST 2 Student’s t-distribution A(t,n), with t = A, and n =  B.
              UPPER 1 The highest (maximum) value of A.
              XOR 2 B if A == NaN, else A.
              Y0 1 Bessel function of A (2nd kind, order 0).
              Y1 1 Bessel function of A (2nd kind, order 1).
              YN 2 Bessel function of A (2nd kind, order B).
              ZCRIT 1 Critical value for the normal-distribution, with alpha =
              A.

       SYMBOLS
              The following symbols have special meaning:

              PI 3.1415926...
              E  2.7182818...
              T  Table with t-coordinates


OPTIONS

       -A     Requires -N and will partially initialize a  table  with  values
              from  the given file containing t and f(t) only. The t is placed
              in column t_col while f(t) goes into column n_col - 1 (see  -N).

       -C     Select  the  columns  that will be operated on until next occur-
              rence of -C.  List columns  separated  by  commas;  ranges  like
              1,3-5,7 are allowed. -C (no arguments) resets the default action
              of using all columns except time column (see -N).   -Ca  selects
              all columns, including time column, while -Cr reverses (toggles)
              the current choices.

       -H     Input file(s) has Header record(s). Number of header records can
              be  changed  by  editing  your  .gmtdefaults4 file. If used, GMT
              default is 1 header record. Use -Hi if only  input  data  should
              have  header  records  [Default will write out header records if
              the input data have them].

       -N     Select the number of columns and the column number that contains
              the "time" variable. Columns are numbered starting at 0 [2/0].

       -Q     Quick  mode  for  scalar  calculation.  Shorthand  for -Ca -N1/0
              -T0/0/1.

       -S     Only report the first or last row of the results [Default is all
              rows].  This is useful if you have computed a statistic (say the
              MODE) and only want to report a single number instead of  numer-
              ous records with identical values.  Append l to get the last row
              and f to get the first row only [Default].

       -T     Required when no input files are given. Sets  the  t-coordinates
              of  the first and last point and the equidistant sampling inter-
              val for the "time" column (see -N).  If there is no time  column
              (only  data  columns),  give  -T  with  no  arguments; this also
              implies -Ca. Alternatively, give the name of a file whose  first
              column   contains   the   desired  t-coordinates  which  may  be
              irregular.

       -V     Selects verbose mode, which will send progress reports to stderr
              [Default runs "silently"].

       -bi    Selects  binary input. Append s for single precision [Default is
              double].  Append n for the  number  of  columns  in  the  binary
              file(s).

       -bo    Selects binary output. Append s for single precision [Default is
              double].  Append n for the  number  of  columns  in  the  binary
              file(s).


BEWARE

       The  operator  PLM  calculates  the  associated  Legendre polynomial of
       degree L and order M, and its argument is the cosine of the  colatitude
       which must satisfy -1 <= x <= +1. PLM is not normalized.
       All  derivatives  are based on central finite differences, with natural
       boundary conditions.


EXAMPLES

       To take log10 of the average of 2 data files, use

       gmtmath file1.d file2.d ADD 0.5 MUL LOG10 = file3.d

       Given the file  samples.d,  which  holds  seafloor  ages  in  m.y.  and
       seafloor  depth  in m, use the relation depth(in m) = 2500 + 350 * sqrt
       (age) to print the depth anomalies:

       gmtmath samples.d T SQRT 350 MUL 2500 ADD SUB = | lpr

       To take the average of columns  1  and  4-6  in  the  three  data  sets
       sizes.1, sizes.2, and sizes.3, use

       gmtmath -C1,4-6 sizes.1 sizes.2 ADD sizes.3 ADD 3 DIV = ave.d

       To  take the 1-column data set ages.d and calculate the modal value and
       assign it to a variable, try

       set mode_age = ‘gmtmath -S -T ages.d MODE =‘

       To evaluate the dilog(x) function for coordinates  given  in  the  file
       t.d:

       gmtmath -Tt.d T DILOG = dilog.d

       To use gmtmath as a RPN Hewlett-Packard calculator on scalars (i.e., no
       input files) and calculate arbitrary expressions, use  the  -Q  option.
       As  an  example, we will calculate the value of Kei (((1 + 1.75)/2.2) +
       cos (60)) and store the result in the shell variable z:

       set z = ‘gmtmath -Q 1 1.75 ADD 2.2 DIV 60 COSD ADD KEI =‘

       To use gmtmath as a general least squares equation solver, imagine that
       the  current  table  is the augmented matrix [ A | b ] and you want the
       least squares solution x to the matrix equation A * x = b.  The  opera-
       tor  LSQFIT  does this; it is your job to populate the matrix correctly
       first. The -A option will facilitate this. Suppose you have a  2-column
       file  ty.d with t and b(t) and you would like to fit a the model y(t) =
       a + b*t + c*H(t-t0), where H is the Heaviside step function for a given
       t0  = 1.55.  Then, you need a 4-column augmented table loaded with t in
       column 0 and your observed y(t) in column 3.  The calculation becomes

       gmtmath -N4/1 -Aty.d -C0 1 ADD -C2 1.55 STEPT ADD -Ca  LSQFIT  =  solu-
       tion.d

       Note  we  use  the -C option to select which columns we are working on,
       then make active all the columns we need (here all of them,  with  -Ca)
       before calling LSQFIT. The second and fourth columns are preloaded with
       t and y(t), respectively, the other columns are zero.  If  you  already
       have  a  precalculated  table  with the augmented matrix [ A | b ] in a
       file (say lsqsys.d), the least squares solution is simply

       gmtmath -T lsqsys.d LSQFIT = solution.d


BUGS

       Files that have the same name as some operators, e.g.,  ADD,  SIGN,  =,
       etc.  cannot  be read and must not be present in the current directory.
       Piping of files is not allowed on input, but the output can be sent  to
       stdout.   The stack limit is hard-wired to 50.  All functions expecting
       a positive radius (e.g., LOG, KEI, etc.) are passed the absolute  value
       of  their  argument. The DDT and D2DT2 functions only work on regularly
       spaced data.  ROOTS must be the last operator on the stack,  only  fol-
       lowed by =.


REFERENCES

       Abramowitz,  M., and I. A. Stegun, 1964, Handbook of Mathematical Func-
       tions, Applied Mathematics Series, vol. 55, Dover, New York.
       Press, W. H., S. A. Teukolsky, W. T. Vetterling, B. P. Flannery,  1992,
       Numerical Recipes, 2nd edition, Cambridge Univ., New York.


SEE ALSO

       gmt(l), grd2xyz(l), grdedit(l), grdinfo(l), grdmath(l), xyz2grd(l)



GMT4.0                            1 Oct 2004                        GMTMATH(l)

Man(1) output converted with man2html