Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       nearneighbor - A "Nearest neighbor" gridding algorithm

SYNOPSIS

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

DESCRIPTION

       nearneighbor reads arbitrarily located (x,y,z[,w])  triples  [quadruplets]  from  standard
       input  [or xyzfile(s)] and uses a nearest neighbor algorithm to assign an average value to
       each node that have one or more points within a radius centered on the node.  The  average
       value  is  computed  as  a  weighted mean of the nearest point from each sector inside the
       search radius.  The weighting function used is w(r) = 1 / (1 + d ^ 2), where d = 3 *  r  /
       search_radius  and  r  is  distance  from  the  node.   This  weight  is  modulated by the
       observation points' weights [if supplied].

       xyzfile(s)
              3 [or 4, see -W] column ASCII file(s) [or binary, see -b] holding (x,y,z[,w])  data
              values.  If no file is specified, nearneighbor will read from standard input.

       -G     Give the name of the output grid file.

       -I     x_inc  [and  optionally  y_inc]  is  the  grid spacing. Optionally, append a suffix
              modifier.  Geographical (degrees) coordinates: Append m to indicate arc minutes  or
              c  to indicate arc seconds.  If one of the units e, k, i, or n is appended instead,
              the increment is assumed to be given  in  meter,  km,  miles,  or  nautical  miles,
              respectively,  and  will  be  converted  to the equivalent degrees longitude at the
              middle latitude of the region (the conversion depends on ELLIPSOID).  If /y_inc  is
              given  but set to 0 it will be reset equal to x_inc; otherwise it will be converted
              to degrees latitude.  All coordinates: If = is appended then the corresponding  max
              x  (east)  or y (north) may be slightly adjusted to fit exactly the given increment
              [by default the increment may be  adjusted  slightly  to  fit  the  given  domain].
              Finally, instead of giving an increment you may specify the number of nodes desired
              by appending + to the supplied integer argument; the increment is then recalculated
              from  the number of nodes and the domain.  The resulting increment value depends on
              whether you have selected  a  gridline-registered  or  pixel-registered  grid;  see
              Appendix  B  for details.  Note: if -Rgrdfile is used then grid spacing has already
              been initialized; use -I to override the values.

       -N     The circular area centered on each node is divided into sectors  sectors.   Average
              values will only be computed if there is at least one value inside each of at least
              min_sectors of these sectors for a given node.   Nodes  that  fail  this  test  are
              assigned  the value NaN (but see -E).  If min_sectors is omitted it is set to be at
              least 50% of sectors (i.e., rounded up to next integer).  [Default  is  a  quadrant
              search  with  100%  coverage, i.e., sectors = min_sectors = 4].  Note that only the
              nearest value per sector enters into the averaging; the  more  distant  points  are
              ignored.

       -R     xmin, xmax, ymin, and ymax specify the Region of interest.  For geographic regions,
              these limits correspond to west, east, south, and north and you may specify them in
              decimal  degrees  or in [+-]dd:mm[:ss.xxx][W|E|S|N] format.  Append r if lower left
              and upper right map coordinates are given instead of w/e/s/n.  The  two  shorthands
              -Rg and -Rd stand for global domain (0/360 and -180/+180 in longitude respectively,
              with -90/+90 in latitude).  Alternatively, specify the name  of  an  existing  grid
              file  and  the  -R  settings  (and grid spacing, if applicable) are copied from the
              grid.  For calendar  time  coordinates  you  may  either  give  (a)  relative  time
              (relative  to  the  selected  TIME_EPOCH and in the selected TIME_UNIT; append t to
              -JX|x), or (b) absolute time of the form [date]T[clock] (append T  to  -JX|x).   At
              least  one  of  date and clock must be present; the T is always required.  The date
              string must be of the form [-]yyyy[-mm[-dd]] (Gregorian calendar) or yyyy[-Www[-d]]
              (ISO  week  calendar),  while  the clock string must be of the form hh:mm:ss[.xxx].
              The use of delimiters and their type and positions must  be  exactly  as  indicated
              (however, input, output and plot formats are customizable; see gmtdefaults).

       -S     Sets  the  search_radius  in  same  units as the grid spacing; append m to indicate
              minutes or c to indicate seconds.  Append k to indicate km (implies -R and  -I  are
              in degrees, and we will use a fast flat Earth approximation to calculate distance).
              For more accuracy,  use  uppercase  K  if  distances  should  be  calculated  along
              geodesics.   However,  if  the  current  ELLIPSOID  is  spherical then great circle
              calculations are used.

OPTIONS

       -E     Set the value assigned to empty nodes [NaN].

       -F     Force  pixel  node  registration  [Default  is   gridline   registration].    (Node
              registrations are defined in GMT Cookbook Appendix B on grid file formats.)

       -H     Input  file(s) has header record(s).  If used, the default number of header records
              is N_HEADER_RECS.  Use -Hi if only input data should have header  records  [Default
              will  write  out header records if the input data have them]. Blank lines and lines
              starting with # are always skipped.  Not used with binary data.

       -L     Boundary condition flag may be x or y or xy indicating data is periodic in range of
              x  or  y  or both set by -R, or flag may be g indicating geographical conditions (x
              and y are lon and lat).  [Default is no boundary conditions].

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

       -:     Toggles  between (longitude,latitude) and (latitude,longitude) input and/or output.
              [Default is (longitude,latitude)].  Append i to select input only or  o  to  select
              output only.  [Default affects both].

       -W     Input  data  have  a  4th  column  containing observation point weights.  These are
              multiplied with the geometrical weight factor to determine the actual weights  used
              in the calculations.

       -bi    Selects  binary  input.   Append  s  for  single precision [Default is d (double)].
              Uppercase S or D will force byte-swapping.  Optionally, append ncol, the number  of
              columns  in your binary input file if it exceeds the columns needed by the program.
              Or append c if the input  file  is  netCDF.  Optionally,  append  var1/var2/...  to
              specify the variables to be read.  [Default is 3 (or 4 if -W is set) columns].

       -f     Special  formatting  of  input  and/or  output columns (time or geographical data).
              Specify i or o to make this apply only to  input  or  output  [Default  applies  to
              both].   Give one or more columns (or column ranges) separated by commas.  Append T
              (absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x
              (longitude),  y  (latitude),  or  f (floating point) to each column or column range
              item.  Shorthand -f[i|o]g means -f[i|o]0x,1y (geographic coordinates).

GRID VALUES PRECISION

       Regardless of the precision of the input data, GMT programs that create  grid  files  will
       internally  hold  the  grids  in  4-byte  floating point arrays.  This is done to conserve
       memory and furthermore most if not all real data can be stored using 4-byte floating point
       values.   Data  with  higher  precision  (i.e.,  double  precision  values) will lose that
       precision once GMT operates on the grid or  writes  out  new  grids.   To  limit  loss  of
       precision  when  processing  data you should always consider normalizing the data prior to
       processing.

EXAMPLES

       To create a gridded data set from the file seaMARCII_bathy.lon_lat_z using a 0.5 min grid,
       a  5  km  search  radius,  using an octant search with 100% sector coverage, and set empty
       nodes to -9999:

       nearneighbor   seaMARCII_bathy.lon_lat_z   -R   242/244/-22/-20   -I   0.5m   -E-9999   -G
       bathymetry.grd -S 5k -N 8/8

       To  make  a  global  grid  file from the data in geoid.xyz using a 1 degree grid, a 200 km
       search radius, spherical distances, using an quadrant search, and set nodes  to  NaN  only
       when fewer than two quadrants contain at least one value:

       nearneighbor geoid.xyz -R 0/360/-90/90 -I 1 -L g -G geoid.grd -S 200K -N 4

SEE ALSO

       blockmean(1), blockmedian(1), blockmode(1), GMT(1), surface(1), triangulate(1)