1BLOCKMODE(1) GMT BLOCKMODE(1)
2
6 blockmode - Block average (x, y, z) data tables by mode estimation
7
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 Note: No space is allowed between the option flag and the associated
16 arguments.
17
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
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 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
55 Specify the region of interest.
56
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 -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 -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 -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 -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 -Q (Quicker) Finds mode z and mean (x,y) [Default finds mode x,
93 mode y, mode z].
94 -V[level] (more ...)
96 Select verbosity level [c].
97 -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 -bi[ncols][t] (more ...)
109 Select native binary input. [Default is 3 (or 4 if -Wi is set)].
110 -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 -d[i|o]nodata (more ...)
116 Replace input columns that equal nodata with NaN and do the
117 reverse on output.
118 -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
120 Only accept data records that match the given pattern.
121 -f[i|o]colinfo (more ...)
123 Specify data types of input and/or output columns.
124 -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
126 Skip or produce header record(s).
127 -icols[+l][+sscale][+ooffset][,...] (more ...)
129 Select input columns and transformations (0 is first column).
130 -ocols[,...] (more ...)
132 Select output columns (0 is first column).
133 -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 -:[i|o] (more ...)
142 Swap 1st and 2nd column on input and/or output.
143 -^ or just -
145 Print a short message about the syntax of the command, then
146 exits (NOTE: on Windows just use -).
147 -+ 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 -? or no arguments
154 Print a complete usage (help) message, including the explanation
155 of all options, then exits.
156
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
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 gmt blockmode hawaii_b.xyg -R198/208/18/25 -I5m -bi3d > hawaii_5x5.xyg
174 To determine the most frequently occurring values per 5x5 block using
176 histogram binning, with data representing integer counts, try
177 gmt blockmode data.txt -R0/100/0/100 -I5 -r -C -D
179
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
1865.4.5 Feb 24, 2019 BLOCKMODE(1)