grdtrend(1)

1GRDTREND(1)                  Generic Mapping Tools                 GRDTREND(1)
2
3
4

NAME

6       grdtrend - Fit and/or remove a polynomial trend in a grid file
7

SYNOPSIS

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

DESCRIPTION

13       grdtrend reads a 2-D grid file and fits a low-order polynomial trend to
14       these  data  by [optionally weighted] least-squares.  The trend surface
15       is defined by:
16
17       m1 + m2*x + m3*y + m4*x*y + m5*x*x + m6*y*y +  m7*x*x*x  +  m8*x*x*y  +
18       m9*x*y*y + m10*y*y*y.
19
20       The user must specify -Nn_model, the number of model parameters to use;
21       thus, -N4 fits a bilinear trend, -N6 a quadratic surface,  and  so  on.
22       Optionally, append r to the -N option to perform a robust fit.  In this
23       case, the program will iteratively reweight the data based on a  robust
24       scale  estimate, in order to converge to a solution insensitive to out‐
25       liers.  This may be handy when separating a  "regional"  field  from  a
26       "residual" which should have non-zero mean, such as a local mountain on
27       a regional surface.
28
29       If data file has values set to NaN, these will be ignored  during  fit‐
30       ting; if output files are written, these will also have NaN in the same
31       locations.
32
33       No space between the option flag and the associated arguments.
34
35       grdfile
36              The name of a 2-D binary grid file.
37
38       -N     [r]n_model sets the number of model parameters to fit.  Append r
39              for robust fit.
40

OPTIONS

42       No space between the option flag and the associated arguments.
43
44       -D     Write the difference (input data - trend) to the file diff.grd.
45
46       -T     Write the fitted trend to the file trend.grd.
47
48       -V     Selects verbose mode, which will send progress reports to stderr
49              [Default runs "silently"].
50
51       -W     If weight.grd exists, it will  be  read  and  used  to  solve  a
52              weighted  least-squares  problem.   [Default:   Ordinary  least-
53              squares fit.]  If the  robust  option  has  been  selected,  the
54              weights used in the robust fit will be written to weight.grd.
55

REMARKS

57       The  domain  of  x  and y will be shifted and scaled to [-1, 1] and the
58       basis functions are built from  Legendre  polynomials.   These  have  a
59       numerical  advantage  in  the form of the matrix which must be inverted
60       and allow more accurate solutions.  NOTE: The model  parameters  listed
61       with  -V are Legendre polynomial coefficients; they are not numerically
62       equivalent to the m#s in the equation described above.  The description
63       above is to allow the user to match -N with the order of the polynomial
64       surface.  See grdmath if you need  to  evaluate  the  trend  using  the
65       reported coefficients.
66

GRID FILE FORMATS

68       By  default GMT writes out grid as single precision floats in a COARDS-
69       complaint netCDF file format.  However, GMT is  able  to  produce  grid
70       files  in  many  other commonly used grid file formats and also facili‐
71       tates so called "packing" of grids, writing out floating point data  as
72       2-  or 4-byte integers. To specify the precision, scale and offset, the
73       user should add the suffix =id[/scale/offset[/nan]], where id is a two-
74       letter  identifier of the grid type and precision, and scale and offset
75       are optional scale factor and offset to be applied to all grid  values,
76       and  nan  is  the  value  used  to indicate missing data.  When reading
77       grids, the format is generally automatically recognized.  If  not,  the
78       same  suffix can be added to input grid file names.  See grdreformat(1)
79       and Section 4.17 of the GMT Technical Reference and Cookbook  for  more
80       information.
81
82       When reading a netCDF file that contains multiple grids, GMT will read,
83       by default, the first 2-dimensional grid that can find in that file. To
84       coax  GMT  into  reading another multi-dimensional variable in the grid
85       file, append ?varname to the file name, where varname is  the  name  of
86       the variable. Note that you may need to escape the special meaning of ?
87       in your shell program by putting a backslash in  front  of  it,  or  by
88       placing  the  filename and suffix between quotes or double quotes.  The
89       ?varname suffix can also be used for output grids to specify a variable
90       name  different  from the default: "z".  See grdreformat(1) and Section
91       4.18 of the GMT Technical Reference and Cookbook for more  information,
92       particularly on how to read splices of 3-, 4-, or 5-dimensional grids.
93

EXAMPLES

95       To  remove  a  planar  trend  from  hawaii_topo.grd and write result in
96       hawaii_residual.grd:
97
98       grdtrend hawaii_topo.grd -N3 -Dhawaii_residual.grd
99
100       To do a robust fit of a bicubic surface to hawaii_topo.grd, writing the
101       result  in  hawaii_trend.grd and the weights used in hawaii_weight.grd,
102       and reporting the progress:
103
104       grdtrend hawaii_topo.grd -N10r  -Thawaii_trend.grd  -Whawaii_weight.grd
105       -V
106