NAME
trend2d - Fit a [weighted] [robust] polynomial model for z =
f(x,y) to ascii xyz[w] data.
SYNOPSIS
trend2d -Nn_model[r] [ xyz[w]file ] [ -F<xyzmrw> ] [ - Ccon-
dition_# ] [ -H ][ -I[confidence_level] ] [ -V ] [ -W ] [ -:
]
DESCRIPTION
trend2d reads ascii 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 reweight-
ing 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.
-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 file containing x,y,z [w] values in the first 3
[4] columns. If no file is specified, trend2d will
read from standard input.
-F Specify up to six letters from the set {x y z m r w}
in any order to create columns of ASCII output. x = x,
y = y, z = z, m = model f(x,y), r = residual z - m, w =
weight used in fitting.
-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 spec-
trum 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)]
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, grdtrend, trend1d
REFERENCES
Wessel, P., and W. H. F. Smith, 1995, The Generic Mapping
Tools (GMT) version 3.0 Technical Reference & Cookbook,
SOEST/NOAA.
Wessel, P., and W. H. F. Smith, 1995, New Version of the
Generic Mapping Tools Released, EOS Trans. AGU, 76, p. 329.
Wessel, P., and W. H. F. Smith, 1995, New Version of the
Generic Mapping Tools Released,
http://www.agu.org/eos_elec/95154e.html, Copyright 1995 by
the American Geophysical Union.
Wessel, P., and W. H. F. Smith, 1991, Free Software Helps
Map and Display Data, EOS Trans. AGU, 72, p. 441.
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.