manpagez: man pages & more
man trend2d(1)
Home | html | info | man
trend2d(1)                            GMT                           trend2d(1)




NAME

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


SYNOPSIS

       trend2d [ table ]  -Fxyzmrw  -Nn_model[+r] [ xyz[w]file ]  [   -Ccondi-
       tion_number  ]  [   -I[confidence_level]  ]  [  -V[level] ] [  -W ] [ [
       -bbinary ] [ -dnodata ] [ -eregexp ]  [  -fflags  ]  [  -hheaders  ]  [
       -iflags ] [ -:[i|o] ]

       Note:  No  space  is allowed between the option flag and the associated
       arguments.


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 aregionala field from a aresiduala which
       should  have non-zero mean, such as a local mountain on a regional sur-
       face.


REQUIRED ARGUMENTS

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

       -Nn_model[+r]
              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 -N4+r.


OPTIONAL ARGUMENTS

       table  One or more ASCII [or binary, see -bi]  files  containing  x,y,z
              [w]  values  in  the first 3 [4] columns. If no files are speci-
              fied, trend2d will read from standard input.

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

       -I[confidence_level]
              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[level] (more a|)
              Select verbosity level [c].

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

       -bi[ncols][t] (more a|)
              Select  native  binary  input. [Default is 3 (or 4 if -W is set)
              input columns].

       -bo[ncols][type] (more a|)
              Select native binary output. [Default is 1-6 columns as  set  by
              -F].

       -d[i|o]nodata (more a|)
              Replace  input  columns  that  equal  nodata with NaN and do the
              reverse on output.

       -e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
              Only accept data records that match the given pattern.

       -f[i|o]colinfo (more a|)
              Specify data types of input and/or output columns.

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
              Skip or produce header record(s).

       -icols[+l][+sscale][+ooffset][,^<i>a|] (more a|)
              Select input columns and transformations (0 is first column).

       -:[i|o] (more a|)
              Swap 1st and 2nd column on input and/or output.

       -^ or just -
              Print a short message about the  syntax  of  the  command,  then
              exits (NOTE: on Windows just use -).

       -+ or just +
              Print  an extensive usage (help) message, including the explana-
              tion of any module-specific  option  (but  not  the  GMT  common
              options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation
              of all options, then exits.


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. For evaluat-
       ing Chebyshev polynomials, see grdmath.

       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.


ASCII FORMAT PRECISION

       The ASCII output formats of numerical data are controlled by parameters
       in your gmt.conf file. Longitude and latitude are  formatted  according
       to   FORMAT_GEO_OUT,  absolute  time  is  under  the  control  of  FOR-
       MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point  val-
       ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for-
       mat in effect can lead to loss of precision in ASCII output, which  can
       lead  to  various  problems  downstream.  If you find the output is not
       written with enough precision, consider switching to binary output (-bo
       if  available) or specify more decimals using the FORMAT_FLOAT_OUT set-
       ting.


EXAMPLES

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

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

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

              gmt trend2d data.xzy -Fxyr -N2+r > detrended_data.xyz

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

              gmt trend2d data.xyz -N10+r -I -V


SEE ALSO

       gmt(1), grdmath(1), grdtrend(1), trend1d(1)


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.


COPYRIGHT

       2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe



5.4.2                            Jun 24, 2017                       trend2d(1)

gmt5 5.4.2 - Generated Thu Jun 29 16:44:59 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.