NAME

     grdtrend - Fit and/or remove a polynomial  trend  in  a  grd
     file

SYNOPSIS

     grdtrend grdfile -Nn_model[r] [ -Ddiff.grd ] [ -Ttrend.grd ]
     [ -V ] [ -Wweight.grd ]

DESCRIPTION

     grdtrend reads a 2-D gridded file and fits a low-order poly-
     nomial  trend  to these data by [optionally weighted] least-
     squares.  The trend surface is defined by:

     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 the  - N
     option  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.

     If data file has values set to NaN, these  will  be  ignored
     during fitting; if output files are written, these will also
     have NaN in the same locations.

     No space between the option flag and  the  associated  argu-
     ments.

     grdfile
          The name of a 2-D binary grd file.

     -N    n_model[r] sets the number of model parameters to fit.
          Append r for robust fit.

OPTIONS

     No space between the option flag and  the  associated  argu-
     ments.

     -D    Write the difference (input data - trend) to the  file
          diff.grd.

     -T    Write the fitted trend to the file trend.grd.

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

     -W    If weight.grd exists, it will  be  read  and  used  to
          solve  a  weighted  least-squares  problem.   [Default:
          Ordinary least-squares fit.]  If the robust option  has
          been  selected, the weights used in the robust fit will
          be written to weight.grd.

REMARKS

     The domain of x and y will be shifted and scaled to [-1,  1]
     and the basis functions are built from Legendre polynomials.
     These have a numerical advantage in the form of  the  matrix
     which  must  be  inverted and allow more accurate solutions.
     NOTE: The model parameters listed with -V are Legendre poly-
     nomial  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.

EXAMPLES

     To remove a planar  trend  from  hawaii_topo.grd  and  write
     result in hawaii_residual.grd, try

     grdtrend hawaii_topo.grd -N3 -Dhawaii_residual.grd

     To do a robust fit of a bicubic surface to  hawaii_topo.grd,
     writing  the result in hawaii_trend.grd and the weights used
     in hawaii_weight.grd, and reporting the progress, try

     grdtrend  hawaii_topo.grd  - N10r   -  Thawaii_trend.grd   -
     Whawaii_weight.grd -V

SEE ALSO

     gmt, grdfft, grdfilter

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.