1GMTSELECT(1) GMT GMTSELECT(1)
2
6 gmtselect - Select data table subsets based on multiple spatial crite‐
7 ria
8
10 gmtselect [ table ] [
11 -Amin_area[/min_level/max_level][+ag|i|s|S][+r|l][ppercent] ] [
12 -Cpointfile+ddist[unit] ] [ -Dresolution[+] ] [ -E[fn] ] [ -Fpoly‐
13 gonfile ] [ -Ggridmask ] [ -I[cfglrsz] ] [ -Jparameters ] [ -Lline‐
14 file+ddist[unit][+p] ] [ -Nmaskvalues ] [ -Rregion ] [
15 -Zmin[/max][+ccol] ] [ -V[level] ] [ -bbinary ] [ -dnodata ] [ -ereg‐
16 exp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -oflags ] [
17 -:[i|o] ]
18 Note: No space is allowed between the option flag and the associated
20 arguments.
21
23 gmtselect is a filter that reads (x, y) or (longitude, latitude) posi‐
24 tions from the first 2 columns of infiles [or standard input] and uses
25 a combination of 1-7 criteria to pass or reject the records. Records
26 can be selected based on whether or not they are 1) inside a rectangu‐
27 lar region (-R [and -J]), 2) within dist km of any point in pointfile,
28 3) within dist km of any line in linefile, 4) inside one of the poly‐
29 gons in the polygonfile, 5) inside geographical features (based on
30 coastlines), 6) has z-values within a given range, or 7) inside bins of
31 a grid mask whose nodes are non-zero. The sense of the tests can be
32 reversed for each of these 6 criteria by using the -I option. See
33 option -: on how to read (y,x) or (latitude,longitude) files. Note: If
34 no projection information is used then you must supply -fg to tell gmt‐
35 select that your data are geographical.
36
38 None
39
41 table One or more ASCII (or binary, see -bi[ncols][type]) data table
42 file(s) holding a number of data columns. If no tables are given
43 then we read from standard input.
44 -Amin_area[/min_level/max_level][+ag|i|s|S][+r|l][+ppercent]
46 Features with an area smaller than min_area in km^2 or of hier‐
47 archical level that is lower than min_level or higher than
48 max_level will not be plotted [Default is 0/0/4 (all features)].
49 Level 2 (lakes) contains regular lakes and wide river bodies
50 which we normally include as lakes; append +r to just get
51 river-lakes or +l to just get regular lakes. By default (+ai)
52 we select the ice shelf boundary as the coastline for Antarc‐
53 tica; append +ag to instead select the ice grounding line as
54 coastline. For expert users who wish to print their own Antarc‐
55 tica coastline and islands via psxy you can use +as to skip all
56 GSHHG features below 60S or +aS to instead skip all features
57 north of 60S. Finally, append +ppercent to exclude polygons
58 whose percentage area of the corresponding full-resolution fea‐
59 ture is less than percent. See GSHHG INFORMATION below for more
60 details. Ignored unless -N is set.
61 -Cpointfile+ddist[unit]
63 Pass all records whose location is within dist of any of the
64 points in the ASCII file pointfile. If dist is zero then the 3rd
65 column of pointfile must have each point's individual radius of
66 influence. Distances are Cartesian and in user units; specify
67 -fg to indicate spherical distances and append a distance unit
68 (see UNITS). Alternatively, if -R and -J are used then geo‐
69 graphic coordinates are projected to map coordinates (in cm,
70 inch, or points, as determined by PROJ_LENGTH_UNIT) before
71 Cartesian distances are compared to dist.
72 -Dresolution[+]
74 Ignored unless -N is set. Selects the resolution of the coast‐
75 line data set to use ((f)ull, (h)igh, (i)ntermediate, (l)ow, or
76 (c)rude). The resolution drops off by ~80% between data sets.
77 [Default is l]. Append (+) to automatically select a lower reso‐
78 lution should the one requested not be available [abort if not
79 found]. Note that because the coastlines differ in details it is
80 not guaranteed that a point will remain inside [or outside] when
81 a different resolution is selected.
82 -E[fn] Specify how points exactly on a polygon boundary should be con‐
84 sidered. By default, such points are considered to be inside the
85 polygon. Append n and/or f to change this behavior for the -F
86 and -N options, respectively, so that boundary points are con‐
87 sidered to be outside.
88 -Fpolygonfile
90 Pass all records whose location is within one of the closed
91 polygons in the multiple-segment file polygonfile. For spherical
92 polygons (lon, lat), make sure no consecutive points are sepa‐
93 rated by 180 degrees or more in longitude. Note that polygonfile
94 must be in ASCII regardless of whether -bi is used.
95 -Ggridmask
97 Pass all locations that are inside the valid data area of the
99 grid gridmask.
100 Nodes that are outside are either NaN or zero.
101 -I[cflrsz]
103 Reverses the sense of the test for each of the criteria speci‐
104 fied:
105 c select records NOT inside any point's circle of influence.
107 f select records NOT inside any of the polygons.
109 g will pass records inside the cells with z equal zero of the
111 grid mask in -G.
112 l select records NOT within the specified distance of any line.
114 r select records NOT inside the specified rectangular region.
116 s select records NOT considered inside as specified by -N (and
118 -A, -D).
119 z select records NOT within the range specified by -Z.
121 -Jparameters (more ...)
123 Select map projection.
124 -Llinefile+ddist[unit][+p]
126 Pass all records whose location is within dist of any of the
127 line segments in the ASCII multiple-segment file linefile. If
128 dist is zero then we will scan each sub-header in the linefile
129 for an embedded -Ddist setting that sets each line's individual
130 distance value. Distances are Cartesian and in user units; spec‐
131 ify -fg to indicate spherical distances append a distance unit
132 (see UNITS). Alternatively, if -R and -J are used then geo‐
133 graphic coordinates are projected to map coordinates (in cm,
134 inch, m, or points, as determined by PROJ_LENGTH_UNIT) before
135 Cartesian distances are compared to dist. Append +p to ensure
136 only points whose orthogonal projections onto the nearest
137 line-segment fall within the segments endpoints [Default consid‐
138 ers points "beyond" the line's endpoints.
139 -Nmaskvalues
141 Pass all records whose location is inside specified geographical
142 features. Specify if records should be skipped (s) or kept (k)
143 using 1 of 2 formats:
144 -Nwet/dry.
146 -Nocean/land/lake/island/pond.
148 [Default is s/k/s/k/s (i.e., s/k), which passes all points on
150 dry land].
151 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
153 Specify the region of interest. If no map projection is supplied
154 we implicitly set -Jx1.
155 -V[level] (more ...)
157 Select verbosity level [c].
158 -Zmin[/max][+ccol]
160 Pass all records whose 3rd column (z; col = 2) lies within the
161 given range or is NaN (use -s to skip NaN records). If max is
162 omitted then we test if z equals min instead. Input file must
163 have at least three columns. To indicate no limit on min or max,
164 specify a hyphen (-). If your 3rd column is absolute time then
165 remember to supply -f2T. To specify another column, append
166 +ccol, and to specify several tests just repeat the Z option as
167 many times has you have columns to test. Note: when more than
168 one Z option is given then the Iz option cannot be used.
169 -bi[ncols][t] (more ...)
171 Select native binary input. [Default is 2 input columns].
172 -bo[ncols][type] (more ...)
174 Select native binary output. [Default is same as input].
175 -d[i|o]nodata (more ...)
177 Replace input columns that equal nodata with NaN and do the
178 reverse on output.
179 -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
181 Only accept data records that match the given pattern.
182 -f[i|o]colinfo (more ...)
184 Specify data types of input and/or output columns.
185 -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
187 Determine data gaps and line breaks.
188 -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
190 Skip or produce header record(s).
191 -icols[+l][+sscale][+ooffset][,...] (more ...)
193 Select input columns and transformations (0 is first column).
194 -ocols[,...] (more ...)
196 Select output columns (0 is first column).
197 -s[cols][a|r] (more ...)
199 Set handling of NaN records.
200 -:[i|o] (more ...)
202 Swap 1st and 2nd column on input and/or output.
203 -^ or just -
205 Print a short message about the syntax of the command, then
206 exits (NOTE: on Windows just use -).
207 -+ or just +
209 Print an extensive usage (help) message, including the explana‐
210 tion of any module-specific option (but not the GMT common
211 options), then exits.
212 -? or no arguments
214 Print a complete usage (help) message, including the explanation
215 of all options, then exits.
216
218 For map distance unit, append unit d for arc degree, m for arc minute,
219 and s for arc second, or e for meter [Default], f for foot, k for km, M
220 for statute mile, n for nautical mile, and u for US survey foot. By
221 default we compute such distances using a spherical approximation with
222 great circles. Prepend - to a distance (or the unit is no distance is
223 given) to perform "Flat Earth" calculations (quicker but less accurate)
224 or prepend + to perform exact geodesic calculations (slower but more
225 accurate).
226
228 The ASCII output formats of numerical data are controlled by parameters
229 in your gmt.conf file. Longitude and latitude are formatted according
230 to FORMAT_GEO_OUT, absolute time is under the control of FOR‐
231 MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point val‐
232 ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for‐
233 mat in effect can lead to loss of precision in ASCII output, which can
234 lead to various problems downstream. If you find the output is not
235 written with enough precision, consider switching to binary output (-bo
236 if available) or specify more decimals using the FORMAT_FLOAT_OUT set‐
237 ting.
238 This note applies to ASCII output only in combination with binary or
240 netCDF input or the -: option. See also the note below.
241
243 Unless you are using the -: option, selected ASCII input records are
244 copied verbatim to output. That means that options like -foT and set‐
245 tings like FORMAT_FLOAT_OUT and FORMAT_GEO_OUT will not have any effect
246 on the output. On the other hand, it allows selecting records with
247 diverse content, including character strings, quoted or not, comments,
248 and other non-numerical content.
249
251 If options -C or -L are selected then distances are Cartesian and in
252 user units; use -fg to imply spherical distances in km and geographical
253 (lon, lat) coordinates. Alternatively, specify -R and -J to measure
254 projected Cartesian distances in map units (cm, inch, or points, as
255 determined by PROJ_LENGTH_UNIT).
256 This program has evolved over the years. Originally, the -R and -J were
258 mandatory in order to handle geographic data, but now there is full
259 support for spherical calculations. Thus, -J should only be used if you
260 want the tests to be applied on projected data and not the original
261 coordinates. If -J is used the distances given via -C and -L are pro‐
262 jected distances.
263
265 Segment headers in the input files are copied to output if one or more
266 records from a segment passes the test. Selection is always done point
267 by point, not by segment. That means only points from a segment that
268 pass the test will be included in the output. If you wish to clip the
269 lines and include the new boundary points at the segment ends you must
270 use gmtspatial instead.
271
273 To extract the subset of data set that is within 300 km of any of the
274 points in pts.txt but more than 100 km away from the lines in
275 lines.txt, run
276 gmt select lonlatfile -fg -Cpts.txt+d300k -Llines.txt+d100k -Il > subset
278 Here, you must specify -fg so the program knows you are processing geo‐
280 graphical data.
281 To keep all points in data.txt within the specified region, except the
283 points on land (as determined by the high-resolution coastlines), use
284 gmt select data.txt -R120/121/22/24 -Dh -Nk/s > subset
286 To return all points in quakes.txt that are inside or on the spherical
288 polygon lonlatpath.txt, try
289 gmt select quakes.txt -Flonlatpath.txt -fg > subset1
291 To return all points in stations.txt that are within 5 cm of the point
293 in origin.txt for a certain projection, try
294 gmt select stations.txt -Corigin.txt+d5 -R20/50/-10/20 -JM20c \
296 --PROJ_LENGTH_UNIT=cm > subset2
297 To return all points in quakes.txt that are inside the grid topo.nc
299 where the values are nonzero, try
300 gmt select quakes.txt -Gtopo.nc > subset2
302
304 The coastline database is GSHHG (formerly GSHHS) which is compiled from
305 three sources: World Vector Shorelines (WVS), CIA World Data Bank II
306 (WDBII), and Atlas of the Cryosphere (AC, for Antarctica only). Apart
307 from Antarctica, all level-1 polygons (ocean-land boundary) are derived
308 from the more accurate WVS while all higher level polygons (level 2-4,
309 representing land/lake, lake/island-in-lake, and
310 island-in-lake/lake-in-island-in-lake boundaries) are taken from WDBII.
311 The Antarctica coastlines come in two flavors: ice-front or grounding
312 line, selectable via the -A option. Much processing has taken place to
313 convert WVS, WDBII, and AC data into usable form for GMT: assembling
314 closed polygons from line segments, checking for duplicates, and cor‐
315 recting for crossings between polygons. The area of each polygon has
316 been determined so that the user may choose not to draw features
317 smaller than a minimum area (see -A); one may also limit the highest
318 hierarchical level of polygons to be included (4 is the maximum). The 4
319 lower-resolution databases were derived from the full resolution data‐
320 base using the Douglas-Peucker line-simplification algorithm. The clas‐
321 sification of rivers and borders follow that of the WDBII. See the GMT
322 Cookbook and Technical Reference Appendix K for further details.
323
325 gmt, gmt.conf, gmtconvert, gmtsimplify, gmtspatial, grdlandmask,
326 pscoast
327
329 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
3305.4.5 Feb 24, 2019 GMTSELECT(1)