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


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 pro-
       gram will iteratively reweight the data based on a robust  scale  esti-
       mate, 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 sur-
       face.

       -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 .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 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/output.  [Default is  (longitude,latitude)].   Applies  to
              geographic coordinates only.

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

       -O     Selects  Overlay  plot mode [Default initializes a new plot sys-
              tem].


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
       reduction 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  confi-
       dence_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%
       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 interpolant are  sig-
       nificant 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 parameter, Ann.
       Math. Stat., 35, 73-101.

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



VERSION                              DATE                           TREND2D(l)

Man(1) output converted with man2html