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  ]  [  -Ccondi-
     tion_#  ] [ -H[nrec] ][ -I[confidence_level] ] [ -V ] [ -W ]
     [ -: ] [ -bi[s][n] ] [ -bo[s] ]


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 parame-
     ters  to  use;  thus,  -N4 fits a bilinear trend, -N6 a qua-
     dratic 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  "resi-
     dual" which should have non-zero mean, such as a local moun-
     tain 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] out-
          put.  x = x, y = y, z = z, m = model f(x,y), r =  resi-
          dual 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
          solution.   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 .gmtdefaults
          file.  If used, GMT default is 1 header record.

     -I   Iteratively increase the number  of  model  parameters,
          starting at one, until n_model is reached or the reduc-
          tion 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 itera-
          tive  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 iterative robust fit].  [Default  reads  only
          the first 3 columns.]

     -:   Toggles      between      (longitude,latitude)      and
          (latitude,longitude)    input/output.     [Default   is
          (longitude,latitude)].

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


REMARKS

     The domain of x and y will be shifted and scaled to [-1,  1]
     and  the  basis functions are built from Chebyshev polynomi-
     als.  These have a numerical advantage in the  form  of  the
     matrix  which must be inverted and allow more accurate solu-
     tions.  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  significance  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  reduction  in
     variance  achieved  by  increasing  the number of terms in a
     model is not significant at a very  high  degree  of  confi-
     dence.   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 Devia-
     tion and a formula from Huber [1964], and is  95%  efficient
     when the model residuals have an outlier-free normal distri-
     bution.  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, try:

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

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

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

     To find out how many terms (up to 10) in a  robust  interpo-
     lant are significant in fitting data.xyz, try:

     trend2d data.xyz -N10r -I -V


SEE ALSO

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


REFERENCES

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

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