Provided by: gmt_4.5.6-1_amd64 bug

NAME

       blockmedian - filter to block average (x,y,z) data by L1 norm.

SYNOPSIS

       blockmedian [ xyz[w]file(s) ] -Ixinc[unit][=|+][/yinc[unit][=|+]] -Rxmin/xmax/ymin/ymax[r]
       [ -C ] [ -E[b] ] [ -F ] [ -H[i][nrec] ] [ -Q ] [ -Tquantile ] [ -V ] [ -W[io] ] [  -:[i|o]
       ] [ -b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ -f[i|o]colinfo ]

DESCRIPTION

       blockmedian  reads  arbitrarily located (x,y,z) triples [or optionally weighted quadruples
       (x,y,z,w)] from standard input [or xyz[w]file(s)] and writes to standard output  a  median
       position  and  value  for  every non-empty block in a grid region defined by the -R and -I
       arguments.  Either blockmean, blockmedian, or blockmode should be used as a  pre-processor
       before  running  surface  to  avoid  aliasing  short wavelengths.  These routines are also
       generally useful for decimating or averaging (x,y,z) data.  You can modify  the  precision
       of  the output format by editing the D_FORMAT parameter in your .gmtdefaults4 file, or you
       may choose binary input and/or output using single or double precision storage.

       xyz[w]file(s)
              3 [or 4] column ASCII file(s) [or binary, see -b] holding (x,y,z[,w]) data  values.
              [w]  is an optional weight for the data.  If no file is specified, blockmedian will
              read from standard input.

       -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.

       -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).

OPTIONS

       -C     Use  the  center of the block as the output location [Default uses the median x and
              median y as location (but see -Q)]..

       -E     Provide Extended report which includes s (the L1  scale  of  the  median),  l,  the
              lowest  value,  and  h,  the  high  value  for  each  block.  Output  order becomes
              x,y,z,s,l,h[,w]. [Default outputs x,y,z[,w].  For box-and-whisker calculation,  use
              -Eb  which will output x,y,z,l,q25,q75,h[,w], where q25 and q75 are the 25% and 75%
              quantiles, respectively.  See -W for w output.

       -F     Force  pixel  node  registration  [Default  is   gridline   registration].    (Node
              registrations  are  defined in GMT Cookbook Appendix B on grid file formats.)  Each
              block is the locus of points nearest the grid value location.   For  example,  with
              -R10/15/10/15  and  and  -I1:   with  the  -F  option 10 <= (x,y) < 11 is one of 25
              blocks; without it 9.5 <= (x,y) < 10.5 is one of 36 blocks.

       -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.

       -Q     (Quicker)  Finds  median z and (x, y) at that the median z [Default finds median x,
              median y independent of z].  Also see -C.

       -T     Sets the quantile of the distribution to be returned [Default is 0.5 which  returns
              the median z].  Here, 0 < quantile < 1.

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

       -W     Weighted modifier[s].  Unweighted input and output has 3  columns  x,y,z;  Weighted
              i/o has 4 columns x,y,z,w.  Weights can be used in input to construct weighted mean
              values in blocks.  Weight sums can  be  reported  in  output  for  later  combining
              several  runs,  etc.   Use -W for weighted i/o, -Wi for weighted inputonly, -Wo for
              weighted output only.  [Default uses unweighted i/o].

       -:     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].

       -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 -Wi is set)].

       -bo    Selects binary output.  Append s for single  precision  [Default  is  d  (double)].
              Uppercase  S or D will force byte-swapping.  Optionally, append ncol, the number of
              desired columns in your binary output file.  [Default is 3 (or 4 if -Wo  is  set)].
              -E adds 3 additional 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).

ASCII FORMAT PRECISION

       The ASCII  output  formats  of  numerical  data  are  controlled  by  parameters  in  your
       .gmtdefaults4    file.     Longitude    and    latitude   are   formatted   according   to
       OUTPUT_DEGREE_FORMAT, whereas other values are formatted according to D_FORMAT.  Be  aware
       that  the  format in effect can lead to loss of precision in the output, which can lead to
       various problems downstream.  If you find the output is not written with enough precision,
       consider  switching to binary output (-bo if available) or specify more decimals using the
       D_FORMAT setting.

EXAMPLES

       To find 5 by 5 minute block medians from the double precision binary data in  hawaii_b.xyg
       and output an ASCII table, run

       blockmedian hawaii_b.xyg -R198/208/18/25 -I5m -bi3 > hawaii_5x5.xyg

       To  compute the shape of a data distribution per bin via a box-and-whisker diagram we need
       the 0%, 25%, 50%, 75%, and 100% quantiles.  To do so on a global 5 by 5 degree basis  from
       the ASCII table depths.xyz and send output to an ASCII table, run

       blockmedian depths.xyz -Rg -I5 -F -Eb > depths_5x5.txt

SEE ALSO

       blockmean(1),   blockmode(1),   GMT(1),   gmtdefaults(1),   nearneighbor(1),   surface(1),
       triangulate(1)