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(l), grdfft(l), grdfilter(l)