1GMTSELECT(1) Generic Mapping Tools GMTSELECT(1)
2
6 gmtselect - Select data subsets based on multiple spatial criteria
7
9 gmtselect [ infiles ] [ -Amin_area[/min_level/max_level][+r|l][pper‐
10 cent] ] [ -C[f]dist/ptfile ] [ -Dresolution[+] ] [ -Fpolygonfile ] [
11 -H[i][nrec] ] [ -I[cflrsz] ] [ -Jparameters ] [ -L[p]dist/linefile ] [
12 -Nmaskvalues[o] ] [ -Rwest/east/south/north[r] ] [ -V ] [ -Zmin/max] ]
13 [ -:[i|o] ] [ -b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ -f[i|o]colinfo ] [
14 -m[i|o][flag] ]
15
17 gmtselect is a filter that reads (longitude, latitude) positions from
18 the first 2 columns of infiles [or standard input] and uses a combina‐
19 tion of 1-6 criteria to pass or reject the records. Records can be
20 selected based on whether or not they are 1) inside a rectangular
21 region (-R [and -J]), 2) within dist km of any point in ptfile, 3)
22 within dist km of any line in linefile, 4) inside one of the polygons
23 in the polygonfile, 5) inside geographical features (based on coast‐
24 lines), or 6) has z-values within a given range. The sense of the
25 tests can be reversed for each of these 6 criteria by using the -I
26 option. See option -: on how to read (latitude,longitude) files.
27 infiles
29 ASCII (or binary, see -b) data file(s) to be operated on. If
30 not given, standard input is read.
31
33 No space between the option flag and the associated arguments.
34 -A Features with an area smaller than min_area in km^2 or of hier‐
36 archical level that is lower than min_level or higher than
37 max_level will not be plotted [Default is 0/0/4 (all features)].
38 Level 2 (lakes) contains regular lakes and wide river bodies
39 which we normally include as lakes; append +r to just get river-
40 lakes or +l to just get regular lakes (requires GSHHS 2.0.1 or
41 higher). Finally, append +ppercent to exclude polygons whose
42 percentage area of the corresponding full-resolution feature is
43 less than percent (requires GSHHS 2.0 or higher). See GSHHS
44 INFORMATION below for more details. Ignored unless -N is set.
45 -C Pass all records whose location is within dist of any of the
47 points in the ASCII file ptfile. If dist is zero then the 3rd
48 column of ptfile must have each point's individual radius of
49 influence. Distances are Cartesian and in user units; specify
50 -fg to indicate spherical distances in km. Use -Cf to indicate
51 you want flat Earth distances (quicker but approximate) rather
52 than geodesic distances (slower but exact). If ELLIPSOID is
53 spherical then geodesics become great circles (faster to compute
54 than geodesic). Alternatively, if -R and -J are used then geo‐
55 graphic coordinates are projected to map coordinates (in cm,
56 inch, m, or points, as determined by MEASURE_UNIT) before Carte‐
57 sian distances are compared to dist.
58 -D Ignored unless -N is set. Selects the resolution of the coast‐
60 line data set to use ((f)ull, (h)igh, (i)ntermediate, (l)ow, or
61 (c)rude). The resolution drops off by ~80% between data sets.
62 [Default is l]. Append + to automatically select a lower reso‐
63 lution should the one requested not be available [abort if not
64 found]. Note that because the coastlines differ in details it
65 is not guaranteed that a point will remain inside [or outside]
66 when a different resolution is selected.
67 -F Pass all records whose location is within one of the closed
69 polygons in the multiple-segment file polygonfile. For spheri‐
70 cal polygons (lon, lat), make sure no consecutive points are
71 separated by 180 degrees or more in longitude. Note that poly‐
72 gonfile must be in ASCII regardless of whether -b is used.
73 -H Input file(s) has header record(s). If used, the default number
75 of header records is N_HEADER_RECS. Use -Hi if only input data
76 should have header records [Default will write out header
77 records if the input data have them]. Blank lines and lines
78 starting with # are always skipped.
79 -I Reverses the sense of the test for each of the criteria speci‐
81 fied:
82 c select records NOT inside any point's circle of influ‐
83 ence.
84 f select records NOT inside any of the polygons.
85 l select records NOT within the specified distance of any
86 line.
87 r select records NOT inside the specified rectangular
88 region.
89 s select records NOT considered inside as specified by -N
90 (and -A, -D).
91 z select records NOT within the range specified by -Z.
92 -J Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or
94 width in UNIT (upper case modifier). UNIT is cm, inch, or m,
95 depending on the MEASURE_UNIT setting in .gmtdefaults4, but this
96 can be overridden on the command line by appending c, i, or m to
97 the scale/width value. When central meridian is optional,
98 default is center of longitude range on -R option. Default
99 standard parallel is the equator. For map height, max dimen‐
100 sion, or min dimension, append h, +, or - to the width, respec‐
101 tively.
102 More details can be found in the psbasemap man pages.
103 CYLINDRICAL PROJECTIONS:
105 -Jclon0/lat0/scale (Cassini)
107 -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
108 -Jj[lon0/]scale (Miller)
109 -Jm[lon0/[lat0/]]scale (Mercator)
110 -Jmlon0/lat0/scale (Mercator - Give meridian and standard paral‐
111 lel)
112 -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and
113 azimuth)
114 -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
115 -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and
116 pole)
117 -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
118 -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
119 -Juzone/scale (UTM - Universal Transverse Mercator)
120 -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)
121 CONIC PROJECTIONS:
123 -Jblon0/lat0/lat1/lat2/scale (Albers)
125 -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
126 -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
127 -Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)
128 AZIMUTHAL PROJECTIONS:
130 -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
132 -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
133 -Jflon0/lat0[/horizon]/scale (Gnomonic)
134 -Jglon0/lat0[/horizon]/scale (Orthographic)
135 -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale
136 (General Perspective).
137 -Jslon0/lat0[/horizon]/scale (General Stereographic)
138 MISCELLANEOUS PROJECTIONS:
140 -Jh[lon0/]scale (Hammer)
142 -Ji[lon0/]scale (Sinusoidal)
143 -Jkf[lon0/]scale (Eckert IV)
144 -Jk[s][lon0/]scale (Eckert VI)
145 -Jn[lon0/]scale (Robinson)
146 -Jr[lon0/]scale (Winkel Tripel)
147 -Jv[lon0/]scale (Van der Grinten)
148 -Jw[lon0/]scale (Mollweide)
149 NON-GEOGRAPHICAL PROJECTIONS:
151 -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
153 -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log,
154 and power scaling)
155 -L Pass all records whose location is within dist of any of the
157 line segments in the ASCII multiple-segment file linefile. If
158 dist is zero then the 2nd column of each sub-header in the
159 ptfile must have each lines's individual distance value. Dis‐
160 tances are Cartesian and in user units; specify -fg to indicate
161 spherical distances in km. If ELLIPSOID is spherical then
162 geodesics become great circles (faster to compute than geodes‐
163 ic). Alternatively, if -R and -J are used then geographic coor‐
164 dinates are projected to map coordinates (in cm, inch, m, or
165 points, as determined by MEASURE_UNIT) before Cartesian dis‐
166 tances are compared to dist. Use -Lp to ensure only points
167 whose orthogonal projections onto the nearest line-segment fall
168 within the segments endpoints [Default considers points "beyond"
169 the line's endpoints.
170 -N Pass all records whose location is inside specified geographical
172 features. Specify if records should be skipped (s) or kept (k)
173 using 1 of 2 formats:
174 -Nwet/dry.
175 -Nocean/land/lake/island/pond.
176 Append o to let points exactly on feature boundaries be consid‐
177 ered outside the feature [Default is inside]. [Default is
178 s/k/s/k/s (i.e., s/k), which passes all points on dry land].
179 -R xmin, xmax, ymin, and ymax specify the Region of interest. For
181 geographic regions, these limits correspond to west, east,
182 south, and north and you may specify them in decimal degrees or
183 in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
184 and upper right map coordinates are given instead of w/e/s/n.
185 The two shorthands -Rg and -Rd stand for global domain (0/360
186 and -180/+180 in longitude respectively, with -90/+90 in lati‐
187 tude). Alternatively, specify the name of an existing grid file
188 and the -R settings (and grid spacing, if applicable) are copied
189 from the grid. For calendar time coordinates you may either
190 give (a) relative time (relative to the selected TIME_EPOCH and
191 in the selected TIME_UNIT; append t to -JX|x), or (b) absolute
192 time of the form [date]T[clock] (append T to -JX|x). At least
193 one of date and clock must be present; the T is always required.
194 The date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
195 calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
196 string must be of the form hh:mm:ss[.xxx]. The use of delim‐
197 iters and their type and positions must be exactly as indicated
198 (however, input, output and plot formats are customizable; see
199 gmtdefaults). If no map projection is supplied we implicitly
200 set -Jx1. Note: only supply -J when your -R is indicating a rec‐
201 tangular region in the projected coordinates (i.e., an oblique
202 projection).
203 -V Selects verbose mode, which will send progress reports to stderr
205 [Default runs "silently"].
206 -Z Pass all records whose 3rd column (z) lies within the given
208 range. Input file must have at least three columns. To indi‐
209 cate no limit on min or max, specify a hyphen (-). If your 3rd
210 column is absolute time then remember to supply -f2T.
211 -: Toggles between (longitude,latitude) and (latitude,longitude)
213 input and/or output. [Default is (longitude,latitude)]. Append
214 i to select input only or o to select output only. [Default
215 affects both].
216 -bi Selects binary input. Append s for single precision [Default is
218 d (double)]. Uppercase S or D will force byte-swapping.
219 Optionally, append ncol, the number of columns in your binary
220 input file if it exceeds the columns needed by the program. Or
221 append c if the input file is netCDF. Optionally, append
222 var1/var2/... to specify the variables to be read. [Default is
223 2 input columns].
224 -bo Selects binary output. Append s for single precision [Default
226 is d (double)]. Uppercase S or D will force byte-swapping.
227 Optionally, append ncol, the number of desired columns in your
228 binary output file. [Default is same as input].
229 -f Special formatting of input and/or output columns (time or geo‐
231 graphical data). Specify i or o to make this apply only to
232 input or output [Default applies to both]. Give one or more
233 columns (or column ranges) separated by commas. Append T (abso‐
234 lute calendar time), t (relative time in chosen TIME_UNIT since
235 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
236 to each column or column range item. Shorthand -f[i|o]g means
237 -f[i|o]0x,1y (geographic coordinates).
238 -m Multiple segment file(s). Segments are separated by a special
240 record. For ASCII files the first character must be flag
241 [Default is '>']. For binary files all fields must be NaN and
242 -b must set the number of output columns explicitly. By default
243 the -m setting applies to both input and output. Use -mi and
244 -mo to give separate settings to input and output. The -m
245 option make sure that segment headers in the input files are
246 copied to output, but it has no effect on the data selection.
247 Selection is always done point by point, not by segment.
248
250 The ASCII output formats of numerical data are controlled by parameters
251 in your .gmtdefaults4 file. Longitude and latitude are formatted
252 according to OUTPUT_DEGREE_FORMAT, whereas other values are formatted
253 according to D_FORMAT. Be aware that the format in effect can lead to
254 loss of precision in the output, which can lead to various problems
255 downstream. If you find the output is not written with enough preci‐
256 sion, consider switching to binary output (-bo if available) or specify
257 more decimals using the D_FORMAT setting.
258 This note applies to ASCII output only in combination with binary or
259 netCDF input or the -: option. See also the note below.
260
262 Unless you are using the -: option, selected ASCII input records are
263 copied verbatim to output. That means that options like -foT and set‐
264 tings like D_FORMAT and OUTPUT_DEGREE_FORMAT will not have any effect
265 on the output. On the other hand, it allows selecting records with
266 diverse content, including character strings, quoted or not, comments,
267 and other non-numerical content.
268
270 If options -C or -L are selected then distances are Cartesian and in
271 user units; use -fg to imply spherical distances in km and geographical
272 (lon, lat) coordinates. Alternatively, specify -R and -J to measure
273 projected Cartesian distances in map units (cm, inch, m, or points, as
274 determined by MEASURE_UNIT).
275 This program has evolved over the years. Originally, the -R and -J
276 were mandatory in order to handle geographic data, but now there is
277 full support for spherical calculations. Thus, -J should only be used
278 if you want the tests to be applied on projected data and not the orig‐
279 inal coordinates. If -J is used the distances given via -C and -L are
280 projected distances.
281
283 To extract the subset of data set that is within 300 km of any of the
284 points in pts.d but more than 100 km away from the lines in lines.d,
285 run
286 gmtselect lonlatfile -fg -C300/pts.d -L100/lines.d -Il > subset
288 Here, you must specify -fg so the program knows you are processing geo‐
290 graphical data (otherwise 300 would be interpreted as Cartesian dis‐
291 tance in x-y units instead of km).
292 To keep all points in data.d within the specified region, except the
294 points on land (as determined by the high-resolution coastlines), use
295 gmtselect data.d -R120/121/22/24 -Dh -Nk/s > subset
297 To return all points in quakes.d that are inside the spherical polygon
299 lonlatpath.d, try
300 gmtselect quakes.d -Flonlatpath.d -fg > subset1
302 To return all points in stations.d that are within 5 cm of the point in
304 origin.d for a certain projection, try
305 gmtselect stations.d -Forigin.d -R20/50/-10/20 -JM20c > subset2
307
309 The coastline database is GSHHS which is compiled from two sources:
310 World Vector Shorelines (WVS) and CIA World Data Bank II (WDBII). In
311 particular, all level-1 polygons (ocean-land boundary) are derived from
312 the more accurate WVS while all higher level polygons (level 2-4, rep‐
313 resenting land/lake, lake/island-in-lake, and island-in-lake/lake-in-
314 island-in-lake boundaries) are taken from WDBII. Much processing has
315 taken place to convert WVS and WDBII data into usable form for GMT:
316 assembling closed polygons from line segments, checking for duplicates,
317 and correcting for crossings between polygons. The area of each poly‐
318 gon has been determined so that the user may choose not to draw fea‐
319 tures smaller than a minimum area (see -A); one may also limit the
320 highest hierarchical level of polygons to be included (4 is the maxi‐
321 mum). The 4 lower-resolution databases were derived from the full res‐
322 olution database using the Douglas-Peucker line-simplification algo‐
323 rithm. The classification of rivers and borders follow that of the
324 WDBII. See the GMT Cookbook and Technical Reference Appendix K for
325 further details.
326
328 gmtdefaults(1), GMT(1), grdlandmask(1), pscoast(1)
329GMT 4.5.6 10 Mar 2011 GMTSELECT(1)