GMTSELECT(1) Generic Mapping Tools GMTSELECT(1)NAMEgmtselect - Select data subsets based on multiple spatial criteria
SYNOPSISgmtselect [ infiles ] [ -Amin_area[/min_level/max_level][+r|l][pper‐
cent] ] [ -C[f]dist/ptfile ] [ -Dresolution[+] ] [ -Fpolygonfile ] [
-H[i][nrec] ] [ -I[cflrsz] ] [ -Jparameters ] [ -L[p]dist/linefile ] [
-Nmaskvalues[o] ] [ -Rwest/east/south/north[r] ] [ -V ] [ -Zmin/max] ]
[ -:[i|o] ] [ -b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ -f[i|o]colinfo ] [
-m[i|o][flag] ]
DESCRIPTIONgmtselect is a filter that reads (longitude, latitude) positions from
the first 2 columns of infiles [or standard input] and uses a combina‐
tion of 1-6 criteria to pass or reject the records. Records can be
selected based on whether or not they are 1) inside a rectangular
region (-R [and -J]), 2) within dist km of any point in ptfile, 3)
within dist km of any line in linefile, 4) inside one of the polygons
in the polygonfile, 5) inside geographical features (based on coast‐
lines), or 6) has z-values within a given range. The sense of the
tests can be reversed for each of these 6 criteria by using the -I
option. See option -: on how to read (latitude,longitude) files.
infiles
ASCII (or binary, see -b) data file(s) to be operated on. If
not given, standard input is read.
OPTIONS
No space between the option flag and the associated arguments.
-A Features with an area smaller than min_area in km^2 or of hier‐
archical level that is lower than min_level or higher than
max_level will not be plotted [Default is 0/0/4 (all features)].
Level 2 (lakes) contains regular lakes and wide river bodies
which we normally include as lakes; append +r to just get river-
lakes or +l to just get regular lakes (requires GSHHS 2.0.1 or
higher). Finally, append +ppercent to exclude polygons whose
percentage area of the corresponding full-resolution feature is
less than percent (requires GSHHS 2.0 or higher). See GSHHS
INFORMATION below for more details. Ignored unless -N is set.
-C Pass all records whose location is within dist of any of the
points in the ASCII file ptfile. If dist is zero then the 3rd
column of ptfile must have each point's individual radius of
influence. Distances are Cartesian and in user units; specify
-fg to indicate spherical distances in km. Use -Cf to indicate
you want flat Earth distances (quicker but approximate) rather
than geodesic distances (slower but exact). If ELLIPSOID is
spherical then geodesics become great circles (faster to compute
than geodesic). Alternatively, if -R and -J are used then geo‐
graphic coordinates are projected to map coordinates (in cm,
inch, m, or points, as determined by MEASURE_UNIT) before Carte‐
sian distances are compared to dist.
-D Ignored unless -N is set. Selects the resolution of the coast‐
line data set to use ((f)ull, (h)igh, (i)ntermediate, (l)ow, or
(c)rude). The resolution drops off by ~80% between data sets.
[Default is l]. Append + to automatically select a lower reso‐
lution should the one requested not be available [abort if not
found]. Note that because the coastlines differ in details it
is not guaranteed that a point will remain inside [or outside]
when a different resolution is selected.
-F Pass all records whose location is within one of the closed
polygons in the multiple-segment file polygonfile. For spheri‐
cal polygons (lon, lat), make sure no consecutive points are
separated by 180 degrees or more in longitude. Note that poly‐
gonfile must be in ASCII regardless of whether -b is used.
-H Input file(s) has header record(s). If used, the default number
of header records is N_HEADER_RECS. Use -Hi if only input data
should have header records [Default will write out header
records if the input data have them]. Blank lines and lines
starting with # are always skipped.
-I Reverses the sense of the test for each of the criteria speci‐
fied:
c select records NOT inside any point's circle of influ‐
ence.
f select records NOT inside any of the polygons.
l select records NOT within the specified distance of any
line.
r select records NOT inside the specified rectangular
region.
s select records NOT considered inside as specified by -N
(and -A, -D).
z select records NOT within the range specified by -Z.
-J Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or
width in UNIT (upper case modifier). UNIT is cm, inch, or m,
depending on the MEASURE_UNIT setting in .gmtdefaults4, but this
can be overridden on the command line by appending c, i, or m to
the scale/width value. When central meridian is optional,
default is center of longitude range on -R option. Default
standard parallel is the equator. For map height, max dimen‐
sion, or min dimension, append h, +, or - to the width, respec‐
tively.
More details can be found in the psbasemap man pages.
CYLINDRICAL PROJECTIONS:
-Jclon0/lat0/scale (Cassini)
-Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
-Jj[lon0/]scale (Miller)
-Jm[lon0/[lat0/]]scale (Mercator)
-Jmlon0/lat0/scale (Mercator - Give meridian and standard paral‐
lel)
-Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and
azimuth)
-Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
-Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and
pole)
-Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
-Jtlon0/[lat0/]scale (TM - Transverse Mercator)
-Juzone/scale (UTM - Universal Transverse Mercator)
-Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)
CONIC PROJECTIONS:
-Jblon0/lat0/lat1/lat2/scale (Albers)
-Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
-Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
-Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)
AZIMUTHAL PROJECTIONS:
-Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
-Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
-Jflon0/lat0[/horizon]/scale (Gnomonic)
-Jglon0/lat0[/horizon]/scale (Orthographic)
-Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale
(General Perspective).
-Jslon0/lat0[/horizon]/scale (General Stereographic)
MISCELLANEOUS PROJECTIONS:
-Jh[lon0/]scale (Hammer)
-Ji[lon0/]scale (Sinusoidal)
-Jkf[lon0/]scale (Eckert IV)
-Jk[s][lon0/]scale (Eckert VI)
-Jn[lon0/]scale (Robinson)
-Jr[lon0/]scale (Winkel Tripel)
-Jv[lon0/]scale (Van der Grinten)
-Jw[lon0/]scale (Mollweide)
NON-GEOGRAPHICAL PROJECTIONS:
-Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
-Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log,
and power scaling)
-L Pass all records whose location is within dist of any of the
line segments in the ASCII multiple-segment file linefile. If
dist is zero then the 2nd column of each sub-header in the
ptfile must have each lines's individual distance value. Dis‐
tances are Cartesian and in user units; specify -fg to indicate
spherical distances in km. If ELLIPSOID is spherical then
geodesics become great circles (faster to compute than geodes‐
ic). Alternatively, if -R and -J are used then geographic coor‐
dinates are projected to map coordinates (in cm, inch, m, or
points, as determined by MEASURE_UNIT) before Cartesian dis‐
tances are compared to dist. Use -Lp to ensure only points
whose orthogonal projections onto the nearest line-segment fall
within the segments endpoints [Default considers points "beyond"
the line's endpoints.
-N Pass all records whose location is inside specified geographical
features. Specify if records should be skipped (s) or kept (k)
using 1 of 2 formats:
-Nwet/dry.
-Nocean/land/lake/island/pond.
Append o to let points exactly on feature boundaries be consid‐
ered outside the feature [Default is inside]. [Default is
s/k/s/k/s (i.e., s/k), which passes all points on dry land].
-R xmin, xmax, ymin, and ymax specify the Region of interest. For
geographic regions, these limits correspond to west, east,
south, and north and you may specify them in decimal degrees or
in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
and upper right map coordinates are given instead of w/e/s/n.
The two shorthands -Rg and -Rd stand for global domain (0/360
and -180/+180 in longitude respectively, with -90/+90 in lati‐
tude). Alternatively, specify the name of an existing grid file
and the -R settings (and grid spacing, if applicable) are copied
from the grid. For calendar time coordinates you may either
give (a) relative time (relative to the selected TIME_EPOCH and
in the selected TIME_UNIT; append t to -JX|x), or (b) absolute
time of the form [date]T[clock] (append T to -JX|x). At least
one of date and clock must be present; the T is always required.
The date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
string must be of the form hh:mm:ss[.xxx]. The use of delim‐
iters and their type and positions must be exactly as indicated
(however, input, output and plot formats are customizable; see
gmtdefaults). If no map projection is supplied we implicitly
set -Jx 1. Note: only supply -J when your -R is indicating a
rectangular region in the projected coordinates (i.e., an
oblique projection).
-V Selects verbose mode, which will send progress reports to stderr
[Default runs "silently"].
-Z Pass all records whose 3rd column (z) lies within the given
range, or is NaN. Input file must have at least three columns.
To indicate no limit on min or max, specify a hyphen (-). If
your 3rd column is absolute time then remember to supply -f 2T.
-: Toggles between (longitude,latitude) and (latitude,longitude)
input and/or output. [Default is (longitude,latitude)]. Append
i to select input only or o to select output only. [Default
affects both].
-bi Selects binary input. Append s for single precision [Default is
d (double)]. Uppercase S or D will force byte-swapping.
Optionally, append ncol, the number of columns in your binary
input file if it exceeds the columns needed by the program. Or
append c if the input file is netCDF. Optionally, append
var1/var2/... to specify the variables to be read. [Default is
2 input columns].
-bo Selects binary output. Append s for single precision [Default
is d (double)]. Uppercase S or D will force byte-swapping.
Optionally, append ncol, the number of desired columns in your
binary output file. [Default is same as input].
-f Special formatting of input and/or output columns (time or geo‐
graphical data). Specify i or o to make this apply only to
input or output [Default applies to both]. Give one or more
columns (or column ranges) separated by commas. Append T (abso‐
lute calendar time), t (relative time in chosen TIME_UNIT since
TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
to each column or column range item. Shorthand -f[i|o]g means
-f[i|o]0x,1y (geographic coordinates).
-m Multiple segment file(s). Segments are separated by a special
record. For ASCII files the first character must be flag
[Default is '>']. For binary files all fields must be NaN and
-b must set the number of output columns explicitly. By default
the -m setting applies to both input and output. Use -mi and
-mo to give separate settings to input and output. The -m
option make sure that segment headers in the input files are
copied to output, but it has no effect on the data selection.
Selection is always done point by point, not by segment.
ASCII FORMAT PRECISION
The ASCII output formats of numerical data are controlled by parameters
in your .gmtdefaults4 file. Longitude and latitude are formatted
according to OUTPUT_DEGREE_FORMAT, whereas other values are formatted
according to D_FORMAT. Be aware that the format in effect can lead to
loss of precision in the output, which can lead to various problems
downstream. If you find the output is not written with enough preci‐
sion, consider switching to binary output (-bo if available) or specify
more decimals using the D_FORMAT setting.
This note applies to ASCII output only in combination with binary or
netCDF input or the -: option. See also the note below.
NOTE ON PROCESSING ASCII INPUT RECORDS
Unless you are using the -: option, selected ASCII input records are
copied verbatim to output. That means that options like -foT and set‐
tings like D_FORMAT and OUTPUT_DEGREE_FORMAT will not have any effect
on the output. On the other hand, it allows selecting records with
diverse content, including character strings, quoted or not, comments,
and other non-numerical content.
NOTE ON DISTANCES
If options -C or -L are selected then distances are Cartesian and in
user units; use -fg to imply spherical distances in km and geographical
(lon, lat) coordinates. Alternatively, specify -R and -J to measure
projected Cartesian distances in map units (cm, inch, m, or points, as
determined by MEASURE_UNIT).
This program has evolved over the years. Originally, the -R and -J
were mandatory in order to handle geographic data, but now there is
full support for spherical calculations. Thus, -J should only be used
if you want the tests to be applied on projected data and not the orig‐
inal coordinates. If -J is used the distances given via -C and -L are
projected distances.
EXAMPLES
To extract the subset of data set that is within 300 km of any of the
points in pts.d but more than 100 km away from the lines in lines.d,
run
gmtselect lonlatfile -fg -C 300/pts.d -L 100/lines.d -Il > subset
Here, you must specify -fg so the program knows you are processing geo‐
graphical data (otherwise 300 would be interpreted as Cartesian dis‐
tance in x-y units instead of km).
To keep all points in data.d within the specified region, except the
points on land (as determined by the high-resolution coastlines), use
gmtselect data.d -R 120/121/22/24 -Dh -Nk/s > subset
To return all points in quakes.d that are inside the spherical polygon
lonlatpath.d, try
gmtselect quakes.d -F lonlatpath.d -fg > subset1
To return all points in stations.d that are within 5 cm of the point in
origin.d for a certain projection, try
gmtselect stations.d -F origin.d -R 20/50/-10/20 -JM 20c > subset2
GSHHS INFORMATION
The coastline database is GSHHS which is compiled from two sources:
World Vector Shorelines (WVS) and CIA World Data Bank II (WDBII). In
particular, all level-1 polygons (ocean-land boundary) are derived from
the more accurate WVS while all higher level polygons (level 2-4, rep‐
resenting land/lake, lake/island-in-lake, and island-in-lake/lake-in-
island-in-lake boundaries) are taken from WDBII. Much processing has
taken place to convert WVS and WDBII data into usable form for GMT:
assembling closed polygons from line segments, checking for duplicates,
and correcting for crossings between polygons. The area of each poly‐
gon has been determined so that the user may choose not to draw fea‐
tures smaller than a minimum area (see -A); one may also limit the
highest hierarchical level of polygons to be included (4 is the maxi‐
mum). The 4 lower-resolution databases were derived from the full res‐
olution database using the Douglas-Peucker line-simplification algo‐
rithm. The classification of rivers and borders follow that of the
WDBII. See the GMT Cookbook and Technical Reference Appendix K for
further details.
SEE ALSOgmtdefaults(1), GMT(1), grdlandmask(1), pscoast(1)GMT 4.5.14 1 Nov 2015 GMTSELECT(1)
