NAME

       grdtrend - Fit trend surface to grids and compute residuals

SYNOPSIS

       grdtrend  grdfile   -Nn_model[+r]  [   -Ddiff.nc  ]  [   -Rregion  ]  [   -Ttrend.nc  ]  [
       -Wweight.nc ]

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

DESCRIPTION

       grdtrend reads a 2-D grid file and fits a low-order polynomial  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 parameters to use; thus, -N3  fits  a
       bilinear trend, -N6 a quadratic 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.

REQUIRED ARGUMENTS

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

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

OPTIONAL ARGUMENTS

       -Ddiff.nc
              Write the difference (input data - trend) to the file diff.nc.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
              Specify the region of interest. Using the -R option will select a subsection of the
              input  grid. If this subsection exceeds the boundaries of the grid, only the common
              region will be extracted.

       -Ttrend.nc
              Write the fitted trend to the file trend.nc.

       -V[level] (more ...)
              Select verbosity level [c].

       -Wweight.nc
              If weight.nc 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.nc.

       -^ 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  explanation  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 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 polynomial 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. See grdmath if you need  to
       evaluate the trend using the reported coefficients.

GRID FILE FORMATS

       By  default  GMT  writes  out grid as single precision floats in a COARDS-complaint netCDF
       file format. However, GMT is able to produce grid files in many other commonly  used  grid
       file formats and also facilitates so called "packing" of grids, writing out floating point
       data as 1- or 2-byte integers. (more ...)

EXAMPLES

       To remove a planar trend from hawaii_topo.nc and write result in hawaii_residual.nc:

              gmt grdtrend hawaii_topo.nc -N3 -Dhawaii_residual.nc

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

              gmt grdtrend hawaii_topo.nc -N10+r -Thawaii_trend.nc -Whawaii_weight.nc -V

SEE ALSO

       gmt, grdfft, grdfilter, grdmath

COPYRIGHT

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