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

NAME

6       nearneighbor - A "Nearest neighbor" gridding algorithm
7

SYNOPSIS

9       nearneighbor         [         xyzfile(s)        ]        -Gout_grdfile
10       -Ixinc[unit][=|+][/yinc[unit][=|+]]             -Nsectors[/min_sectors]
11       -Rwest/east/south/north[r]  -Ssearch_radius[m|c|k|K] [ -Eempty ] [ -F ]
12       [  -H[i][nrec]  ]  [  -Lflag  ]  [  -V  ]  [  -W  ]  [  -:[i|o]   ]   [
13       -bi[s|S|d|D[ncol]|c[var1/...]] ] [ -fcolinfo ]
14

DESCRIPTION

16       nearneighbor  reads  arbitrarily  located  (x,y,z[,w]) triples [quadru‐
17       plets] from standard input [or xyzfile(s)] and uses a nearest  neighbor
18       algorithm to assign an average value to each node that have one or more
19       points within a radius centered on the node.  The average value is com‐
20       puted  as  a weighted mean of the nearest point from each sector inside
21       the search radius.  The weighting function used is w(r) = 1 / (1 + d  ^
22       2),  where  d  = 3 * r / search_radius and r is distance from the node.
23       This weight is modulated by the observation points'  weights  [if  sup‐
24       plied].
25
26       xyzfile(s)
27              3  [or 4, see -W] column ASCII file(s) [or binary, see -b] hold‐
28              ing  (x,y,z[,w])  data  values.   If  no  file   is   specified,
29              nearneighbor will read from standard input.
30
31       -G     Give the name of the output grid file.
32
33       -I     x_inc  [and  optionally  y_inc] is the grid spacing. Optionally,
34              append a suffix modifier.  Geographical  (degrees)  coordinates:
35              Append  m  to indicate arc minutes or c to indicate arc seconds.
36              If one of the units e, k, i,  or  n  is  appended  instead,  the
37              increment  is assumed to be given in meter, km, miles, or nauti‐
38              cal miles, respectively, and will be converted to the equivalent
39              degrees longitude at the middle latitude of the region (the con‐
40              version depends on ELLIPSOID).  If /y_inc is given but set to  0
41              it  will be reset equal to x_inc; otherwise it will be converted
42              to degrees latitude.  All coordinates: If = is appended then the
43              corresponding max x (east) or y (north) may be slightly adjusted
44              to fit exactly the given increment [by default the increment may
45              be adjusted slightly to fit the given domain].  Finally, instead
46              of giving an increment you  may  specify  the  number  of  nodes
47              desired  by  appending  +  to the supplied integer argument; the
48              increment is then recalculated from the number of nodes and  the
49              domain.   The  resulting  increment value depends on whether you
50              have selected a gridline-registered  or  pixel-registered  grid;
51              see Appendix B for details.
52
53       -N     The  circular area centered on each node is divided into sectors
54              sectors.  Average values will only be computed if  there  is  at
55              least one value inside at least min_sectors of the sectors for a
56              given node.  Nodes that fail this test are  assigned  the  value
57              NaN  (but see -E).  If min_sectors is omitted, each sector needs
58              to have at least one value  inside  it.   [Default  is  quadrant
59              search,  i.e.,  sectors  = min_sectors = 4].  Note that only the
60              nearest value per sector enters into the averaging, not all val‐
61              ues inside the circle.
62
63       -R     xmin,  xmax, ymin, and ymax specify the Region of interest.  For
64              geographic regions,  these  limits  correspond  to  west,  east,
65              south,  and north and you may specify them in decimal degrees or
66              in [+-]dd:mm[:ss.xxx][W|E|S|N] format.  Append r if  lower  left
67              and  upper  right  map coordinates are given instead of w/e/s/n.
68              The two shorthands -Rg and -Rd stand for  global  domain  (0/360
69              and  -180/+180  in longitude respectively, with -90/+90 in lati‐
70              tude).  For calendar time coordinates you may  either  give  (a)
71              relative  time  (relative  to the selected TIME_EPOCH and in the
72              selected TIME_UNIT; append t to -JX|x), or (b) absolute time  of
73              the  form  [date]T[clock]  (append T to -JX|x).  At least one of
74              date and clock must be present; the T is always  required.   The
75              date  string  must  be  of the form [-]yyyy[-mm[-dd]] (Gregorian
76              calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
77              string  must  be  of the form hh:mm:ss[.xxx].  The use of delim‐
78              iters and their type and positions must be exactly as  indicated
79              (however,  input,  output and plot formats are customizable; see
80              gmtdefaults).
81
82       -S     Sets the search_radius in same units as the grid spacing; append
83              m  to  indicate  minutes  or c to indicate seconds.  Append k to
84              indicate km (implies -R and -I are in degrees, and we will use a
85              fast  flat Earth approximation to calculate distance).  For more
86              accuracy, use uppercase K  if  distances  should  be  calculated
87              along  geodesics.   However,  if the current ELLIPSOID is set to
88              Sphere then spherical great circle calculations are used.
89

OPTIONS

91       -E     Set the value assigned to empty nodes [NaN].
92
93       -F     Force pixel node registration  [Default  is  gridline  registra‐
94              tion].  (Node registrations are defined in GMT Cookbook Appendix
95              B on grid file formats.)
96
97       -H     Input file(s) has Header record(s).  Number  of  header  records
98              can be changed by editing your .gmtdefaults4 file.  If used, GMT
99              default is 1 header record. Use -Hi if only  input  data  should
100              have  header  records  [Default will write out header records if
101              the input data have them]. Blank lines and lines starting with #
102              are always skipped.  Not used with binary data.
103
104       -L     Boundary  condition  flag may be x or y or xy indicating data is
105              periodic in range of x or y or both set by -R, or flag may be  g
106              indicating  geographical  conditions  (x and y are lon and lat).
107              [Default is no boundary conditions].
108
109       -V     Selects verbose mode, which will send progress reports to stderr
110              [Default runs "silently"].
111
112       -:     Toggles  between  (longitude,latitude)  and (latitude,longitude)
113              input and/or output.  [Default is (longitude,latitude)].  Append
114              i  to  select  input  only or o to select output only.  [Default
115              affects both].
116
117       -W     Input data  have  a  4th  column  containing  observation  point
118              weights.   These are multiplied with the geometrical weight fac‐
119              tor to determine the actual weights used in the calculations.
120
121       -bi    Selects binary input.  Append s for single precision [Default is
122              d  (double)].   Uppercase  S  or  D  will  force  byte-swapping.
123              Optionally, append ncol, the number of columns  in  your  binary
124              input  file if it exceeds the columns needed by the program.  Or
125              append c  if  the  input  file  is  netCDF.  Optionally,  append
126              var1/var2/...  to specify the variables to be read.  [Default is
127              3 (or 4 if -W is set) columns].
128
129       -f     Special formatting of input and/or output columns (time or  geo‐
130              graphical  data).   Specify  i  or  o to make this apply only to
131              input or output [Default applies to both].   Give  one  or  more
132              columns (or column ranges) separated by commas.  Append T (abso‐
133              lute calendar time), t (relative time in chosen TIME_UNIT  since
134              TIME_EPOCH),  x (longitude), y (latitude), or f (floating point)
135              to each column or column range item.  Shorthand  -f[i|o]g  means
136              -f[i|o]0x,1y (geographic coordinates).
137

GRID VALUES PRECISION

139       Regardless of the precision of the input data, GMT programs that create
140       gridded files will internally hold the grids in 4-byte  floating  point
141       arrays.  This is done to conserve memory and futhermore most if not all
142       real data can be stored using 4-byte floating point values.  Data  with
143       higher  precision (i.e., double precision values) will lose that preci‐
144       sion once GMT operates on the grid or writes out new grids.   To  limit
145       loss  of precision when processing data you should always consider nor‐
146       malizing the data prior to processing.
147

EXAMPLES

149       To create a gridded data set from  the  file  seaMARCII_bathy.lon_lat_z
150       using a 0.5 min grid, a 5 km search radius, using an octant search, and
151       set empty nodes to -9999:
152
153       nearneighbor seaMARCII_bathy.lon_lat_z -R242/244/-22/-20 -I.5m  -E-9999
154       -Gbathymetry.grd -S5k -N8
155
156       To  make  a  global  gridded  file from the data in geoid.xyz using a 1
157       degree grid, a 200 km search  radius,  spherical  distances,  using  an
158       quadrant  search,  and  set nodes to NaN only when fewer than two quad‐
159       rants contain at least one value:
160
161       nearneighbor geoid.xyz -R0/360/-90/90 -I1 -Lg -Ggeoid.grd -S200K -N4/2
162

SEE ALSO

164       blockmean(1), blockmedian(1), blockmode(1), GMT(1), surface(1),  trian‐
165       gulate(1)
166
167
168
169GMT 4.3.1                         15 May 2008                  NEARNEIGHBOR(1)
Impressum