1BLOCKMODE(1)                          GMT                         BLOCKMODE(1)
2
3
4

NAME

6       blockmode - Block average (x, y, z) data tables by mode estimation
7

SYNOPSIS

9       blockmode [ table ]
10        -Iincrement
11        -Rregion  [   -C ] [  -D[width][+c][+a|+l|+h ] [  -Er|s[-] ] [  -Q ] [
12       -V[level] ] [  -W[i|o][+s] ] [ -bbinary ] [ -dnodata ] [ -eregexp  ]  [
13       -fflags ] [ -hheaders ] [ -iflags ] [ -oflags ] [ -r ] [ -:[i|o] ]
14
15       Note:  No  space  is allowed between the option flag and the associated
16       arguments.
17

DESCRIPTION

19       blockmode reads arbitrarily  located  (x,y,z)  triples  [or  optionally
20       weighted  quadruples  (x,y,z,w)]  from  standard  input  [or table] and
21       writes to standard output mode estimates  of  position  and  value  for
22       every  non-empty  block in a grid region defined by the -R and -I argu‐
23       ments. Either blockmean, blockmedian, or blockmode should be used as  a
24       pre-processor  before  running  surface  to  avoid aliasing short wave‐
25       lengths. These routines are also generally  useful  for  decimating  or
26       averaging (x,y,z) data. You can modify the precision of the output for‐
27       mat by editing the FORMAT_FLOAT_OUT parameter in your gmt.conf file, or
28       you may choose binary input and/or output to avoid loss of precision.
29

REQUIRED ARGUMENTS

31       -Ixinc[unit][+e|n][/yinc[unit][+e|n]]
32              x_inc  [and  optionally  y_inc] is the grid spacing. Optionally,
33              append a suffix modifier.  Geographical  (degrees)  coordinates:
34              Append  m  to indicate arc minutes or s to indicate arc seconds.
35              If one of the units e, f, k, M, n or u is appended instead,  the
36              increment  is assumed to be given in meter, foot, km, Mile, nau‐
37              tical mile or US survey foot, respectively,  and  will  be  con‐
38              verted  to  the equivalent degrees longitude at the middle lati‐
39              tude of the region (the conversion depends  on  PROJ_ELLIPSOID).
40              If  y_inc is given but set to 0 it will be reset equal to x_inc;
41              otherwise it will be converted to degrees latitude. All  coordi‐
42              nates:  If +e is appended then the corresponding max x (east) or
43              y (north) may be slightly adjusted  to  fit  exactly  the  given
44              increment  [by default the increment may be adjusted slightly to
45              fit the given domain]. Finally, instead of giving  an  increment
46              you  may  specify the number of nodes desired by appending +n to
47              the supplied integer argument; the increment  is  then  recalcu‐
48              lated  from  the  number  of nodes and the domain. The resulting
49              increment value depends on whether you  have  selected  a  grid‐
50              line-registered  or  pixel-registered grid; see App-file-formats
51              for details. Note: if -Rgrdfile is used then  the  grid  spacing
52              has already been initialized; use -I to override the values.
53
54       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
55              Specify the region of interest.
56

OPTIONAL ARGUMENTS

58       table  3 [or 4, see -W] column ASCII data table file(s) [or binary, see
59              -bi] holding (x,y,z[,w]) data values. [w] is an optional  weight
60              for  the data. If no file is specified, blockmode will read from
61              standard input.
62
63       -C     Use the center of the block as the output location [Default uses
64              the modal xy location (but see -Q)]. -C overrides -Q.
65
66       -D[width][+c][+a|+l|+h ]
67              Perform unweighted mode calculation via histogram binning, using
68              the specified histogram width. Append +c to center bins so  that
69              their  mid point is a multiple of width [uncentered].  If multi‐
70              ple modes are found for a block we return the average mode [+a].
71              Append  +l or +h to return the low of high mode instead, respec‐
72              tively.  If width is not given it will  default  to  1  provided
73              your data set only contains integers. Also, for integer data and
74              integer bin width we enforce bin centering (+c) and  select  the
75              lowest  mode  (+l) if there are multiples. [Default mode is nor‐
76              mally the Least Median of Squares (LMS) statistic].
77
78       -E     Provide Extended report which includes s (the L1  scale  of  the
79              mode),  l,  the  lowest  value,  and  h, the high value for each
80              block. Output order becomes  x,y,z,s,l,h[,w].  [Default  outputs
81              x,y,z[,w]. See -W for w output.
82
83       -Er|s[-]
84              Provide  source id s or record number r output, i.e., append the
85              source id or record number associated with the modal  value.  If
86              tied then report the record number of the higher of the two val‐
87              ues; append - to instead report the record number of  the  lower
88              value.   Note that both -E and -Er[-] may be specified.  For -Es
89              we expect input records of the form x,y,z[,w],sid, where sid  is
90              an unsigned integer source id.
91
92       -Q     (Quicker)  Finds  mode  z  and mean (x,y) [Default finds mode x,
93              mode y, mode z].
94
95       -V[level] (more ...)
96              Select verbosity level [c].
97
98       -W[i|o][+s]
99              Weighted modifier[s]. Unweighted input and output have 3 columns
100              x,y,z;  Weighted i/o has 4 columns x,y,z,w.  Weights can be used
101              in input to construct weighted  modal  values  for  each  block.
102              Weight  sums  can be reported in output for later combining sev‐
103              eral runs, etc. Use -W for weighted i/o, -Wi for weighted  input
104              only, and -Wo for weighted output only. [Default uses unweighted
105              i/o].  If your weights are actually  uncertainties  (one  sigma)
106              then append +s and we compute weight = 1/sigma.
107
108       -bi[ncols][t] (more ...)
109              Select native binary input. [Default is 3 (or 4 if -Wi is set)].
110
111       -bo[ncols][type] (more ...)
112              Select  native  binary  output.  [Default  is  3 (or 4 if -Wo is
113              set)]. -E adds 3 additional columns.
114
115       -d[i|o]nodata (more ...)
116              Replace input columns that equal nodata  with  NaN  and  do  the
117              reverse on output.
118
119       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
120              Only accept data records that match the given pattern.
121
122       -f[i|o]colinfo (more ...)
123              Specify data types of input and/or output columns.
124
125       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
126              Skip or produce header record(s).
127
128       -icols[+l][+sscale][+ooffset][,...] (more ...)
129              Select input columns and transformations (0 is first column).
130
131       -ocols[,...] (more ...)
132              Select output columns (0 is first column).
133
134       -r (more ...)
135              Set  pixel node registration [gridline]. Each block is the locus
136              of points nearest the grid value location. Consider  an  example
137              with -R10/15/10/15 and -I1: With the -r option, 10 <= (x,y) < 11
138              is one of 25 blocks; without it 9.5 <= (x,y) < 10.5 is one of 36
139              blocks.
140
141       -:[i|o] (more ...)
142              Swap 1st and 2nd column on input and/or output.
143
144       -^ or just -
145              Print  a  short  message  about  the syntax of the command, then
146              exits (NOTE: on Windows just use -).
147
148       -+ or just +
149              Print an extensive usage (help) message, including the  explana‐
150              tion  of  any  module-specific  option  (but  not the GMT common
151              options), then exits.
152
153       -? or no arguments
154              Print a complete usage (help) message, including the explanation
155              of all options, then exits.
156

ASCII FORMAT PRECISION

158       The ASCII output formats of numerical data are controlled by parameters
159       in your gmt.conf file. Longitude and latitude are  formatted  according
160       to   FORMAT_GEO_OUT,  absolute  time  is  under  the  control  of  FOR‐
161       MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point  val‐
162       ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for‐
163       mat in effect can lead to loss of precision in ASCII output, which  can
164       lead  to  various  problems  downstream.  If you find the output is not
165       written with enough precision, consider switching to binary output (-bo
166       if  available) or specify more decimals using the FORMAT_FLOAT_OUT set‐
167       ting.
168

EXAMPLES

170       To find 5 by 5 minute block mode estimates from  the  double  precision
171       binary data in hawaii_b.xyg and output an ASCII table, run:
172
173              gmt blockmode hawaii_b.xyg -R198/208/18/25 -I5m -bi3d > hawaii_5x5.xyg
174
175       To  determine  the most frequently occurring values per 5x5 block using
176       histogram binning, with data representing integer counts, try
177
178              gmt blockmode data.txt -R0/100/0/100 -I5 -r -C -D
179

SEE ALSO

181       blockmean, blockmedian, gmt, gmt.conf, greenspline, nearneighbor,  sph‐
182       triangulate, surface, triangulate
183
185       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
186
187
188
189
1905.4.5                            Feb 24, 2019                     BLOCKMODE(1)
Impressum