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] ] [
10 -C[f]dist/ptfile ] [ -Dresolution ] [ -Fpolygonfile ] [ -H[i][nrec] ] [
11 -I[cflrs] ] [ -Jparameters ] [ -L[p]dist/linefile ] [ -M[i|o][flag] ] [
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
16 gmtselect is a filter that reads (longitude, latitude) positions from
17 the first 2 columns of infiles [or standard input] and uses a combina‐
18 tion of 1-6 criteria to pass or reject the records. Records can be
19 selected based on whether or not they are 1) inside a rectangular
20 region (-R [and -J]), 2) within dist km of any point in ptfile, 3)
21 within dist km of any line in linefile, 4) inside one of the polygons
22 in the polygonfile, 5) inside geographical features (based on coast‐
23 lines), or 6) has z-values within a given range. The sense of the
24 tests can be reversed for each of these 6 criteria by using the -I
25 option. See option -: on how to read (latitude,longitude) files.
26 infiles
28 ASCII (or binary, see -b) data file(s) to be operated on. If
29 not given, standard input is read.
30
32 No space between the option flag and the associated arguments.
33 -A Ignored unless -N is set. Geographical features with an area
35 smaller than min_area in km^2 or of hierarchical level that is
36 lower than min_level or higher than max_level will be ignored
37 [Default is 0/4 (all features)]. See DATABASE INFORMATION in the
38 pscoast man-pages for more details.
39 -C Pass all records whose location is within dist of any of the
41 points in the ASCII file ptfile. If dist is zero then the 3rd
42 column of ptfile must have each point's Distances are Cartesian
43 and in user units; specify -fg to indicate spherical distances
44 in km. Use -Cf to indicate you want flat Earth distances
45 (quicker but approximate) rather than geodesic distances (slower
46 but exact). If ELLIPSOID is Sphere then geodesics become great
47 circles (faster to compute than geodesic). Alternatively, if -R
48 and -J are used then geographic coordinates are projected to map
49 coordinates (in cm, inch, m, or points, as determined by MEA‐
50 SURE_UNIT) before Cartesian distances are compared to dist.
51 -D Ignored unless -N is set. Selects the resolution of the coast‐
53 line data set to use ((f)ull, (h)igh, (i)ntermediate, (l)ow, or
54 (c)rude). The resolution drops off by ~80% between data sets.
55 [Default is l]. Note that because the coastlines differ in
56 details it is not guaranteed that a point will remain inside [or
57 outside] when a different resolution is selected.
58 -F Pass all records whose location is within one of the closed
60 polygons in the multiple-segment file polygonfile. For spheri‐
61 cal polygons (lon, lat), make sure no consecutive points are
62 separated by 180 degrees or more in longitude. Note that poly‐
63 gonfile must be in ASCII regardless of whether -b is used.
64 -H Input file(s) has Header record(s). Number of header records
66 can be changed by editing your .gmtdefaults4 file. If used, GMT
67 default is 1 header record. Use -Hi if only input data should
68 have header records [Default will write out header records if
69 the input data have them]. Blank lines and lines starting with #
70 are always skipped.
71 -I Reverses the sense of the test for each of the criteria speci‐
73 fied:
74 c select records NOT inside any point's circle of influ‐
75 ence.
76 f select records NOT inside any of the polygons.
77 l select records NOT within the specified distance of any
78 line.
79 r select records NOT inside the specified rectangular
80 region.
81 s select records NOT considered inside as specified by -A,
82 -D, -N.
83 z select records NOT within the range specified by -Z.
84 -J Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or
86 width in UNIT (upper case modifier). UNIT is cm, inch, or m,
87 depending on the MEASURE_UNIT setting in .gmtdefaults4, but this
88 can be overridden on the command line by appending c, i, or m to
89 the scale/width value. When central meridian is optional,
90 default is center of longitude range on -R option. Default
91 standard parallel is the equator. For map height, max dimen‐
92 sion, or min dimension, append h, +, or - to the width, respec‐
93 tively.
94 More details can be found in the psbasemap man pages.
95 CYLINDRICAL PROJECTIONS:
97 -Jclon0/lat0/scale (Cassini)
99 -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
100 -Jj[lon0/]scale (Miller)
101 -Jm[lon0/[lat0/]]scale (Mercator)
102 -Jmlon0/lat0/scale (Mercator - Give meridian and standard paral‐
103 lel)
104 -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and
105 azimuth)
106 -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
107 -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and
108 pole)
109 -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
110 -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
111 -Juzone/scale (UTM - Universal Transverse Mercator)
112 -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)
113 CONIC PROJECTIONS:
115 -Jblon0/lat0/lat1/lat2/scale (Albers)
117 -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
118 -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
119 AZIMUTHAL PROJECTIONS:
121 -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
123 -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
124 -Jflon0/lat0[/horizon]/scale (Gnomonic)
125 -Jglon0/lat0[/horizon]/scale (Orthographic)
126 -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale
127 (General Perspective).
128 -Jslon0/lat0[/horizon][/slat]/scale (General Stereographic)
129 MISCELLANEOUS PROJECTIONS:
131 -Jh[lon0/]scale (Hammer)
133 -Ji[lon0/]scale (Sinusoidal)
134 -Jkf[lon0/]scale (Eckert IV)
135 -Jk[s][lon0/]scale (Eckert IV)
136 -Jn[lon0/]scale (Robinson)
137 -Jr[lon0/]scale (Winkel Tripel)
138 -Jv[lon0/]scale (Van der Grinten)
139 -Jw[lon0/]scale (Mollweide)
140 NON-GEOGRAPHICAL PROJECTIONS:
142 -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
144 -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log,
145 and power scaling)
146 -L Pass all records whose location is within dist of any of the
148 line segments in the ASCII multiple-segment file linefile. If
149 dist is zero then the 2nd column of each sub-header in the
150 ptfile must have each lines's individual distance value. Dis‐
151 tances are Cartesian and in user units; specify -fg to indicate
152 spherical distances in km. Alternatively, if -R and -J are used
153 then geographic coordinates are projected to map coordinates (in
154 cm, inch, m, or points, as determined by MEASURE_UNIT) before
155 Cartesian distances are compared to dist. Use -Lp to ensure
156 only points whose orthogonal projections onto the nearest line-
157 segment fall within the segments endpoints [Default considers
158 points "beyond" the line's endpoints.
159 -M Multiple segment file(s). Segments are separated by a special
161 record. For ASCII files the first character must be flag
162 [Default is '>']. For binary files all fields must be NaN and
163 -b must set the number of output columns explicitly. By default
164 the -M setting applies to both input and output. Use -Mi and
165 -Mo to give separate settings. The -M option make sure that
166 segment headers in the input files are copied to output, but it
167 has no effect on the data selection. Selection is always done
168 point by point, not by segment.
169 -N Pass all records whose location is inside specified geographical
171 features. Specify if records should be skipped (s) or kept (k)
172 using 1 of 2 formats:
173 -Nwet/dry.
174 -Nocean/land/lake/island/pond.
175 Append o to let points exactly on feature boundaries be consid‐
176 ered outside the feature [Default is inside]. [Default is
177 s/k/s/k/s (i.e., s/k), which passes all points on dry land].
178 -R xmin, xmax, ymin, and ymax specify the Region of interest. For
180 geographic regions, these limits correspond to west, east,
181 south, and north and you may specify them in decimal degrees or
182 in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
183 and upper right map coordinates are given instead of w/e/s/n.
184 The two shorthands -Rg and -Rd stand for global domain (0/360
185 and -180/+180 in longitude respectively, with -90/+90 in lati‐
186 tude). For calendar time coordinates you may either give (a)
187 relative time (relative to the selected TIME_EPOCH and in the
188 selected TIME_UNIT; append t to -JX|x), or (b) absolute time of
189 the form [date]T[clock] (append T to -JX|x). At least one of
190 date and clock must be present; the T is always required. The
191 date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
192 calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
193 string must be of the form hh:mm:ss[.xxx]. The use of delim‐
194 iters and their type and positions must be exactly as indicated
195 (however, input, output and plot formats are customizable; see
196 gmtdefaults). If no map projection is supplied we implicitly
197 set -Jx1.
198 -V Selects verbose mode, which will send progress reports to stderr
200 [Default runs "silently"].
201 -Z Pass all records whose 3rd colum (z) lies within the given
203 range. Input file must have at least three columns. To indi‐
204 cate no limit on min or max, specify a hyphen (-).
205 -: Toggles between (longitude,latitude) and (latitude,longitude)
207 input and/or output. [Default is (longitude,latitude)]. Append
208 i to select input only or o to select output only. [Default
209 affects both].
210 -bi Selects binary input. Append s for single precision [Default is
212 d (double)]. Uppercase S or D will force byte-swapping.
213 Optionally, append ncol, the number of columns in your binary
214 input file if it exceeds the columns needed by the program. Or
215 append c if the input file is netCDF. Optionally, append
216 var1/var2/... to specify the variables to be read. [Default is
217 2 input columns].
218 -bo Selects binary output. Append s for single precision [Default
220 is d (double)]. Uppercase S or D will force byte-swapping.
221 Optionally, append ncol, the number of desired columns in your
222 binary output file. [Default is same as input].
223 -f Special formatting of input and/or output columns (time or geo‐
225 graphical data). Specify i or o to make this apply only to
226 input or output [Default applies to both]. Give one or more
227 columns (or column ranges) separated by commas. Append T (abso‐
228 lute calendar time), t (relative time in chosen TIME_UNIT since
229 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
230 to each column or column range item. Shorthand -f[i|o]g means
231 -f[i|o]0x,1y (geographic coordinates).
232
234 The ASCII output formats of numerical data are controlled by parameters
235 in your .gmtdefaults4 file. Longitude and latitude are formatted
236 according to OUTPUT_DEGREE_FORMAT, whereas other values are formatted
237 according to D_FORMAT. Be aware that the format in effect can lead to
238 loss of precision in the output, which can lead to various problems
239 downstream. If you find the output is not written with enough preci‐
240 sion, consider switching to binary output (-bo if available) or specify
241 more decimals using the D_FORMAT setting.
242
244 If options -C or -L are selected then distances are Cartesian and in
245 user units; use -fg to imply spherical distances in km and geographical
246 (lon, lat) coordinates. Alternatively, specify -R and -J to measure
247 projected Cartesian distances in map units (cm, inch, m, or points, as
248 determined by MEASURE_UNIT).
249 This program has evolved over the years. Originally, the -R and -J
250 were mandatory in order to handle geographic data, but now there is
251 full support for spherical calculations. Thus, -J should only be used
252 if you want the tests to be applied on projected data and not the orig‐
253 inal coordinates. If -J is used the distances given via -C and -L are
254 projected distances.
255
257 To extract the subset of data set that is within 300 km of any of the
258 points in pts.d but more than 100 km away from the lines in lines.d,
259 run
260 gmtselect lonlatfile -fg -C300/pts.d -L100/lines.d -Il > subset
262 Here, you must specify -fg so the program knows you are processing geo‐
264 graphical data (otherwise 300 would be interpreted as Cartesian dis‐
265 tance in x-y units instead of km).
266 To keep all points in data.d within the specified region, except the
268 points on land (as determined by the high-resolution coastlines), use
269 gmtselect data.d -R120/121/22/24 -Dh -Nk/s > subset
271 To return all points in quakes.d that are inside the spherical polygon
273 lonlatpath.d, try
274 gmtselect quakes.d -Flonlatpath.d -fg > subset1
276 To return all points in stations.d that are within 5 cm of the point in
278 origin.d for a certain projection, try
279 gmtselect stations.d -Forigin.d -R20/50/-10/20 -JM20c > subset2
281
283 gmtdefaults(1), GMT(1), grdlandmask(1), pscoast(1)
284GMT 4.3.1 15 May 2008 GMTSELECT(1)