gmtselect(1) GMT gmtselect(1)
NAME
gmtselect - Select data table subsets based on multiple spatial crite-
ria
SYNOPSIS
gmtselect [ table ] [
-Amin_area[/min_level/max_level][+ag|i|s|S][+r|l][ppercent] ] [
-Cpointfile+ddist[unit] ] [ -Dresolution[+] ] [ -E[fn] ] [ -Fpoly-
gonfile ] [ -Ggridmask ] [ -I[cfglrsz] ] [ -Jparameters ] [ -Lline-
file+ddist[unit][+p] ] [ -Nmaskvalues ] [ -Rregion ] [
-Zmin[/max][+ccol] ] [ -V[level] ] [ -bbinary ] [ -dnodata ] [ -ereg-
exp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -oflags ] [
-:[i|o] ]
Note: No space is allowed between the option flag and the associated
arguments.
DESCRIPTION
gmtselect is a filter that reads (x, y) or (longitude, latitude) posi-
tions from the first 2 columns of infiles [or standard input] and uses
a combination of 1-7 criteria to pass or reject the records. Records
can be selected based on whether or not they are 1) inside a rectangu-
lar region (-R [and -J]), 2) within dist km of any point in pointfile,
3) within dist km of any line in linefile, 4) inside one of the poly-
gons in the polygonfile, 5) inside geographical features (based on
coastlines), 6) has z-values within a given range, or 7) inside bins of
a grid mask whose nodes are non-zero. 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 (y,x) or (latitude,longitude) files. Note: If
no projection information is used then you must supply -fg to tell gmt-
select that your data are geographical.
REQUIRED ARGUMENTS
None
OPTIONAL ARGUMENTS
table One or more ASCII (or binary, see -bi[ncols][type]) data table
file(s) holding a number of data columns. If no tables are given
then we read from standard input.
-Amin_area[/min_level/max_level][+ag|i|s|S][+r|l][+ppercent]
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. By default (+ai)
we select the ice shelf boundary as the coastline for Antarc-
tica; append +ag to instead select the ice grounding line as
coastline. For expert users who wish to print their own Antarc-
tica coastline and islands via psxy you can use +as to skip all
GSHHG features below 60S or +aS to instead skip all features
north of 60S. Finally, append +ppercent to exclude polygons
whose percentage area of the corresponding full-resolution fea-
ture is less than percent. See GSHHG INFORMATION below for more
details. Ignored unless -N is set.
-Cpointfile+ddist[unit]
Pass all records whose location is within dist of any of the
points in the ASCII file pointfile. If dist is zero then the 3rd
column of pointfile must have each pointas individual radius of
influence. Distances are Cartesian and in user units; specify
-fg to indicate spherical distances and append a distance unit
(see UNITS). Alternatively, if -R and -J are used then geo-
graphic coordinates are projected to map coordinates (in cm,
inch, or points, as determined by PROJ_LENGTH_UNIT) before
Cartesian distances are compared to dist.
-Dresolution[+]
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.
-E[fn] Specify how points exactly on a polygon boundary should be con-
sidered. By default, such points are considered to be inside the
polygon. Append n and/or f to change this behavior for the -F
and -N options, respectively, so that boundary points are con-
sidered to be outside.
-Fpolygonfile
Pass all records whose location is within one of the closed
polygons in the multiple-segment file polygonfile. For spherical
polygons (lon, lat), make sure no consecutive points are sepa-
rated by 180 degrees or more in longitude. Note that polygonfile
must be in ASCII regardless of whether -bi is used.
-Ggridmask
Pass all locations that are inside the valid data area of the
grid gridmask.
Nodes that are outside are either NaN or zero.
-I[cflrsz]
Reverses the sense of the test for each of the criteria speci-
fied:
c select records NOT inside any pointas circle of influence.
f select records NOT inside any of the polygons.
g will pass records inside the cells with z equal zero of the
grid mask in -G.
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.
-Jparameters (more a|)
Select map projection.
-Llinefile+ddist[unit][+p]
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 we will scan each sub-header in the linefile
for an embedded -Ddist setting that sets each lineas individual
distance value. Distances are Cartesian and in user units; spec-
ify -fg to indicate spherical distances append a distance unit
(see UNITS). 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 PROJ_LENGTH_UNIT) before
Cartesian distances are compared to dist. Append +p to ensure
only points whose orthogonal projections onto the nearest
line-segment fall within the segments endpoints [Default consid-
ers points abeyonda the lineas endpoints.
-Nmaskvalues
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.
[Default is s/k/s/k/s (i.e., s/k), which passes all points on
dry land].
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
Specify the region of interest. If no map projection is supplied
we implicitly set -Jx1.
-V[level] (more a|)
Select verbosity level [c].
-Zmin[/max][+ccol]
Pass all records whose 3rd column (z; col = 2) lies within the
given range or is NaN (use -s to skip NaN records). If max is
omitted then we test if z equals min instead. 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 -f2T. To specify another column, append
+ccol, and to specify several tests just repeat the Z option as
many times has you have columns to test. Note: when more than
one Z option is given then the Iz option cannot be used.
-bi[ncols][t] (more a|)
Select native binary input. [Default is 2 input columns].
-bo[ncols][type] (more a|)
Select native binary output. [Default is same as input].
-d[i|o]nodata (more a|)
Replace input columns that equal nodata with NaN and do the
reverse on output.
-e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
Only accept data records that match the given pattern.
-f[i|o]colinfo (more a|)
Specify data types of input and/or output columns.
-g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more a|)
Determine data gaps and line breaks.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
Skip or produce header record(s).
-icols[+l][+sscale][+ooffset][,^<i>a|] (more a|)
Select input columns and transformations (0 is first column).
-ocols[,a|] (more a|)
Select output columns (0 is first column).
-s[cols][a|r] (more a|)
Set handling of NaN records.
-:[i|o] (more a|)
Swap 1st and 2nd column on input and/or output.
-^ or just -
Print a short message about the syntax of the command, then
exits (NOTE: on Windows just use -).
-+ or just +
Print an extensive usage (help) message, including the explana-
tion of any module-specific option (but not the GMT common
options), then exits.
-? or no arguments
Print a complete usage (help) message, including the explanation
of all options, then exits.
UNITS
For map distance unit, append unit d for arc degree, m for arc minute,
and s for arc second, or e for meter [Default], f for foot, k for km, M
for statute mile, n for nautical mile, and u for US survey foot. By
default we compute such distances using a spherical approximation with
great circles. Prepend - to a distance (or the unit is no distance is
given) to perform aFlat Eartha calculations (quicker but less accurate)
or prepend + to perform exact geodesic calculations (slower but more
accurate).
ASCII FORMAT PRECISION
The ASCII output formats of numerical data are controlled by parameters
in your gmt.conf file. Longitude and latitude are formatted according
to FORMAT_GEO_OUT, absolute time is under the control of FOR-
MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point val-
ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for-
mat in effect can lead to loss of precision in ASCII output, which can
lead to various problems downstream. If you find the output is not
written with enough precision, consider switching to binary output (-bo
if available) or specify more decimals using the FORMAT_FLOAT_OUT set-
ting.
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 FORMAT_FLOAT_OUT and FORMAT_GEO_OUT 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, or points, as
determined by PROJ_LENGTH_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 original
coordinates. If -J is used the distances given via -C and -L are pro-
jected distances.
NOTE ON SEGMENTS
Segment headers in the input files are copied to output if one or more
records from a segment passes the test. Selection is always done point
by point, not by segment. That means only points from a segment that
pass the test will be included in the output. If you wish to clip the
lines and include the new boundary points at the segment ends you must
use gmtspatial instead.
EXAMPLES
To extract the subset of data set that is within 300 km of any of the
points in pts.txt but more than 100 km away from the lines in
lines.txt, run
gmt select lonlatfile -fg -Cpts.txt+d300k -Llines.txt+d100k -Il > subset
Here, you must specify -fg so the program knows you are processing geo-
graphical data.
To keep all points in data.txt within the specified region, except the
points on land (as determined by the high-resolution coastlines), use
gmt select data.txt -R120/121/22/24 -Dh -Nk/s > subset
To return all points in quakes.txt that are inside or on the spherical
polygon lonlatpath.txt, try
gmt select quakes.txt -Flonlatpath.txt -fg > subset1
To return all points in stations.txt that are within 5 cm of the point
in origin.txt for a certain projection, try
gmt select stations.txt -Corigin.txt+d5 -R20/50/-10/20 -JM20c \
--PROJ_LENGTH_UNIT=cm > subset2
To return all points in quakes.txt that are inside the grid topo.nc
where the values are nonzero, try
gmt select quakes.txt -Gtopo.nc > subset2
GSHHS INFORMATION
The coastline database is GSHHG (formerly GSHHS) which is compiled from
three sources: World Vector Shorelines (WVS), CIA World Data Bank II
(WDBII), and Atlas of the Cryosphere (AC, for Antarctica only). Apart
from Antarctica, all level-1 polygons (ocean-land boundary) are derived
from the more accurate WVS while all higher level polygons (level 2-4,
representing land/lake, lake/island-in-lake, and
island-in-lake/lake-in-island-in-lake boundaries) are taken from WDBII.
The Antarctica coastlines come in two flavors: ice-front or grounding
line, selectable via the -A option. Much processing has taken place to
convert WVS, WDBII, and AC data into usable form for GMT: assembling
closed polygons from line segments, checking for duplicates, and cor-
recting for crossings between polygons. The area of each polygon has
been determined so that the user may choose not to draw features
smaller than a minimum area (see -A); one may also limit the highest
hierarchical level of polygons to be included (4 is the maximum). The 4
lower-resolution databases were derived from the full resolution data-
base using the Douglas-Peucker line-simplification algorithm. The clas-
sification of rivers and borders follow that of the WDBII. See the GMT
Cookbook and Technical Reference Appendix K for further details.
SEE ALSO
gmt(1), gmt.conf(5), gmtconvert(1), gmtsimplify(1), gmtspatial(1),
grdlandmask(1), pscoast(1)
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 gmtselect(1)
gmt5 5.4.2 - Generated Wed Jun 28 16:33:22 CDT 2017