## NAME

           trend2d  - Fit a [weighted] [robust] polynomial model for z = f(x,y) to
           xyz[w] data.

## SYNOPSIS

           trend2d -F<xyzmrw> -Nn_model[r] [ xyz[w]file  ]  [  -Ccondition_#  ]  [
           -H[nrec] ][ -I[confidence_level] ] [ -V ] [ -W ] [ -: ] [ -bi[s][n] ] [
           -bo[s][n] ] [ -f[i|o]colinfo ]

## DESCRIPTION

           trend2d reads x,y,z [and w] values from the first three [four]  columns
           on  standard  input  [or  xyz[w]file]  and  fits a regression model z =
           f(x,y) + e by [weighted] least squares. The fit may be made  robust  by
           iterative  reweighting  of  the  data. The user may also search for the
           number of terms in f(x,y) which significantly reduce the variance in z.
           n_model  may be in [1,10] to fit a model of the following form (similar
           to grdtrend):

           m1 + m2*x + m3*y + m4*x*y + m5*x*x + m6*y*y +  m7*x*x*x  +  m8*x*x*y  +
           m9*x*y*y + m10*y*y*y.

           The user must specify -Nn_model, the number of model parameters to use;
           thus, -N4 fits a bilinear trend, -N6 a quadratic surface,  and  so  on.
           Optionally, append r to perform a robust fit. In this case, the program
           will iteratively reweight the data based on a robust scale estimate, in
           order  to  converge  to a solution insensitive to outliers. This may be
           handy when separating a "regional" field from a "residual" which should
           have non-zero mean, such as a local mountain on a regional surface.

           -F     Specify  up  to  six  letters  from the set {x y z m r w} in any
                  order to create columns of ASCII [or binary] output. x = x, y  =
                  y,  z = z, m = model f(x,y), r = residual z - m, w = weight used
                  in fitting.

           -N     Specify the number of terms in the model, n_model, and append  r
                  to do a robust fit. E.g., a robust bilinear model is -N4r.

## OPTIONS

           xyz[w]file
                  ASCII  [or  binary,  see -b] file containing x,y,z [w] values in
                  the first 3 [4] columns. If no file is specified,  trend2d  will
                  read from standard input.

           -C     Set  the  maximum  allowed condition number for the matrix solu-
                  tion. trend2d fits a damped least squares model, retaining  only
                  that  part of the eigenvalue spectrum such that the ratio of the
                  largest eigenvalue to the smallest  eigenvalue  is  condition_#.
                  [Default: condition_# = 1.0e06. ].

           -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].

           -I     Iteratively increase the number of model parameters, starting at
                  one, until n_model is reached or the reduction  in  variance  of
                  the  model is not significant at the confidence_level level. You
                  may set -I only, without an attached number; in  this  case  the
                  fit  will  be iterative with a default confidence level of 0.51.
                  Or choose your own level between 0 and 1. See remarks section.

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

           -W     Weights  are  supplied  in  input  column 4. Do a weighted least
                  squares fit [or start with these weights when doing  the  itera-
                  tive robust fit]. [Default reads only the first 3 columns.]

           -:     Toggles  between  (longitude,latitude)  and (latitude,longitude)
                  input and/or output. [Default is (longitude,latitude)].   Append
                  i  to  select  input  only  or o to select output only. [Default
                  affects both].

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

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

           -f     Special formatting of input and output  columns  (time  or  geo-
                  graphical  data)  Specify  i(nput)  or o(utput) [Default is both
                  input and output].  Give one or more columns (or column  ranges)
                  separated by commas.  Append T (Absolute calendar time), t (time
                  relative to chosen TIME_EPOCH), x (longitude), y  (latitude),  g
                  (geographic coordinate), or f (floating point) to each column or
                  column range item.

## REMARKS

           The domain of x and y will be shifted and scaled to  [-1,  1]  and  the
           basis  functions  are  built  from  Chebyshev polynomials. These have a
           numerical advantage in the form of the matrix which  must  be  inverted
           and  allow more accurate solutions. In many applications of trend2d the
           user has data located approximately along a line in the x,y plane which
           makes  an angle with the x axis (such as data collected along a road or
           ship track). In this case the accuracy could be improved by a  rotation
           of the x,y axes.  trend2d does not search for such a rotation; instead,
           it may find that the matrix problem has deficient  rank.  However,  the
           solution  is  computed  using  the generalized inverse and should still
           work out OK.  The user should check the results graphically if  trend2d
           shows  deficient  rank.  NOTE:  The model parameters listed with -V are
           Chebyshev coefficients; they are not numerically equivalent to the  m#s
           in  the equation described above. The description above is to allow the
           user to match -N with the order of the polynomial surface.

           The -Nn_modelr (robust) and -I (iterative) options evaluate the signif-
           icance of the improvement in model misfit Chi-Squared by an F test. The
           default confidence limit is set at 0.51; it can be changed with the  -I
           option. The user may be surprised to find that in most cases the reduc-
           tion in variance achieved by increasing the number of terms in a  model
           is  not  significant  at a very high degree of confidence. For example,
           with 120 degrees of freedom, Chi-Squared must decrease by 26%  or  more
           to  be  significant  at  the  95% confidence level. If you want to keep
           iterating as long as Chi-Squared is decreasing, set confidence_level to
           zero.

           A low confidence limit (such as the default value of 0.51) is needed to
           make the robust method work. This method iteratively reweights the data
           to  reduce the influence of outliers. The weight is based on the Median
           Absolute Deviation and a formula from Huber [1964], and  is  95%  effi-
           cient  when  the  model residuals have an outlier-free normal distribu-
           tion. This means  that  the  influence  of  outliers  is  reduced  only
           slightly  at  each iteration; consequently the reduction in Chi-Squared
           is not very significant. If the procedure needs  a  few  iterations  to
           successfully  attenuate  their  effect, the significance level of the F
           test must be kept low.

## EXAMPLES

           To remove a planar trend from data.xyz by ordinary least squares, use:

           trend2d data.xyz -Fxyr -N2 > detrended_data.xyz

           To make the above planar trend robust with respect to outliers, use:

           trend2d data.xzy -Fxyr -N2r > detrended_data.xyz

           To find out how many terms (up to 10) in a robust interpolant are  sig-
           nificant in fitting data.xyz, use:

           trend2d data.xyz -N10r -I -V

## SEE ALSO

           gmt(l), grdtrend(l), trend1d(l)

## REFERENCES

           Huber,  P.  J.,  1964,  Robust estimation of a location parameter, Ann.
           Math. Stat., 35, 73-101.

           Menke, W., 1989, Geophysical Data Analysis:  Discrete  Inverse  Theory,
           Revised Edition, Academic Press, San Diego.

    GMT4.0                            1 Oct 2004                        TREND2D(l)