.\" Man page generated from reStructuredText.
.
.TH "GMTSELECT" "1gmt" "May 21, 2019" "5.4.5" "GMT"
.SH NAME
gmtselect \- Select data table subsets based on multiple spatial criteria
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBgmtselect\fP [ \fItable\fP ]
[  \fB\-A\fP\fImin_area\fP[/\fImin_level\fP/\fImax_level\fP][\fB+ag\fP|\fBi\fP|\fBs\fP|\fBS\fP][\fB+r\fP|\fBl\fP][\fBp\fP\fIpercent\fP] ]
[  \fB\-C\fP\fIpointfile\fP\fB+d\fP\fIdist\fP[\fIunit\fP] ]
[  \fB\-D\fP\fIresolution\fP[\fB+\fP] ]
[  \fB\-E\fP[\fBfn\fP] ]
[  \fB\-F\fP\fIpolygonfile\fP ]
[  \fB\-G\fP\fIgridmask\fP ]
[  \fB\-I\fP[\fBcfglrsz\fP] ]
[  \fB\-J\fP\fIparameters\fP ]
[  \fB\-L\fP\fIlinefile\fP\fB+d\fP\fIdist\fP[\fIunit\fP][\fB+p\fP] ]
[  \fB\-N\fP\fImaskvalues\fP ]
[  \fB\-R\fP\fIregion\fP ]
[  \fB\-Z\fP\fImin\fP[/\fImax\fP][\fB+c\fP\fIcol\fP] ]
[  \fB\-V\fP[\fIlevel\fP] ]
[ \fB\-b\fPbinary ]
[ \fB\-d\fPnodata ]
[ \fB\-e\fPregexp ]
[ \fB\-f\fPflags ]
[ \fB\-g\fPgaps ]
[ \fB\-h\fPheaders ]
[ \fB\-i\fPflags ]
[ \fB\-o\fPflags ]
[ \fB\-:\fP[\fBi\fP|\fBo\fP] ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
\fBgmtselect\fP is a filter that reads (x, y) or (longitude, latitude) positions from the first 2 columns of \fIinfiles\fP
[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 rectangular region (\fB\-R\fP [and \fB\-J\fP]), 2) within
\fIdist\fP km of any point in \fIpointfile\fP, 3) within \fIdist\fP km of any line in \fIlinefile\fP, 4) inside one of the
polygons in the \fIpolygonfile\fP, 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 \fB\-I\fP option. See option \fB\-:\fP on how to read
(y,x) or (latitude,longitude) files.  Note: If no projection information is used then you must supply \fB\-fg\fP
to tell \fBgmtselect\fP that your data are geographical.
.SH REQUIRED ARGUMENTS
.sp
None
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
.B \fItable\fP
One or more ASCII (or binary, see \fB\-bi\fP[\fIncols\fP][\fItype\fP]) data
table file(s) holding a number of data columns. If no tables are given
then we read from standard input.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-A\fP\fImin_area\fP[/\fImin_level\fP/\fImax_level\fP][\fB+ag\fP|\fBi\fP|\fBs\fP|\fBS\fP][\fB+r\fP|\fBl\fP][\fB+p\fP\fIpercent\fP]
Features with an area smaller than \fImin_area\fP in km^2 or of
hierarchical level that is lower than \fImin_level\fP or higher than
\fImax_level\fP 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 \fB+r\fP to just get river\-lakes
or \fB+l\fP to just get regular lakes.  By default (\fB+ai\fP) we select the ice shelf
boundary as the coastline for Antarctica; append \fB+ag\fP to instead
select the ice grounding line as coastline.  For expert users who wish to
print their own Antarctica coastline and islands via \fIpsxy\fP you can
use \fB+as\fP to skip all GSHHG features below 60S or \fB+aS\fP to instead
skip all features north of 60S.  Finally, append
\fB+p\fP\fIpercent\fP to exclude polygons whose percentage area of the
corresponding full\-resolution feature is less than \fIpercent\fP\&. See
GSHHG INFORMATION below for more details. Ignored unless \fB\-N\fP is set.
.UNINDENT
.INDENT 0.0
.TP
\fB\-C\fP\fIpointfile\fP\fB+d\fP\fIdist\fP[\fIunit\fP]
Pass all records whose location is within \fIdist\fP of any of the
points in the ASCII file \fIpointfile\fP\&. If \fIdist\fP is zero then the 3rd
column of \fIpointfile\fP must have each point\(aqs individual radius of
influence. Distances are Cartesian and in user units; specify
\fB\-fg\fP to indicate spherical distances and append a distance unit
(see UNITS). Alternatively, if \fB\-R\fP and \fB\-J\fP are used then
geographic coordinates are projected to map coordinates (in cm,
inch, or points, as determined by PROJ_LENGTH_UNIT) before
Cartesian distances are compared to \fIdist\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-D\fP\fIresolution\fP[\fB+\fP]
Ignored unless \fB\-N\fP is set. Selects the resolution of the
coastline data set to use ((\fBf\fP)ull, (\fBh\fP)igh,
(\fBi\fP)ntermediate, (\fBl\fP)ow, or (\fBc\fP)rude). The resolution drops
off by ~80% between data sets. [Default is \fBl\fP]. Append (+) to
automatically select a lower resolution 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.
.UNINDENT
.INDENT 0.0
.TP
\fB\-E\fP[\fBfn\fP]
Specify how points exactly on a polygon boundary should be
considered. By default, such points are considered to be inside the
polygon. Append \fBn\fP and/or \fBf\fP to change this behavior for the
\fB\-F\fP and \fB\-N\fP options, respectively, so that boundary points are
considered to be outside.
.UNINDENT
.INDENT 0.0
.TP
\fB\-F\fP\fIpolygonfile\fP
Pass all records whose location is within one of the closed polygons
in the multiple\-segment file \fIpolygonfile\fP\&. For spherical polygons
(lon, lat), make sure no consecutive points are separated by 180
degrees or more in longitude. Note that \fIpolygonfile\fP must be in
ASCII regardless of whether \fB\-bi\fP is used.
.UNINDENT
.INDENT 0.0
.TP
\fB\-G\fP\fIgridmask\fP
.INDENT 7.0
.TP
.B Pass all locations that are inside the valid data area of the grid \fIgridmask\fP\&.
Nodes that are outside are either NaN or zero.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
\fB\-I\fP[\fBcflrsz\fP]
Reverses the sense of the test for each of the criteria specified:
.sp
\fBc\fP select records NOT inside any point\(aqs circle of influence.
.sp
\fBf\fP select records NOT inside any of the polygons.
.sp
\fBg\fP will pass records inside the cells with z equal zero of the grid mask in \-G.
.sp
\fBl\fP select records NOT within the specified distance of any line.
.sp
\fBr\fP select records NOT inside the specified rectangular region.
.sp
\fBs\fP select records NOT considered inside as specified by \fB\-N\fP
(and \fB\-A\fP, \fB\-D\fP).
.sp
\fBz\fP select records NOT within the range specified by \fB\-Z\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-J\fP\fIparameters\fP (more ...)
Select map projection.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-L\fP\fIlinefile\fP\fB+d\fP\fIdist\fP[\fIunit\fP][\fB+p\fP]
Pass all records whose location is within \fIdist\fP of any of the line
segments in the ASCII multiple\-segment file \fIlinefile\fP\&. If \fIdist\fP is
zero then we will scan each sub\-header in the \fIlinefile\fP for an
embedded \fB\-D\fP\fIdist\fP setting that sets each line\(aqs individual
distance value. Distances are Cartesian and in user units; specify
\fB\-fg\fP to indicate spherical distances append a distance unit (see
UNITS). Alternatively, if \fB\-R\fP and \fB\-J\fP are used then geographic
coordinates are projected to map coordinates (in cm, inch, m, or
points, as determined by PROJ_LENGTH_UNIT) before Cartesian
distances are compared to \fIdist\fP\&. Append \fB+p\fP to ensure only points
whose orthogonal projections onto the nearest line\-segment fall
within the segments endpoints [Default considers points "beyond" the
line\(aqs endpoints.
.UNINDENT
.INDENT 0.0
.TP
\fB\-N\fP\fImaskvalues\fP
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:
.sp
\fB\-N\fP\fIwet/dry\fP\&.
.sp
\fB\-N\fP\fIocean/land/lake/island/pond\fP\&.
.sp
[Default is s/k/s/k/s (i.e., s/k), which passes all points on dry land].
.UNINDENT
.INDENT 0.0
.TP
\fB\-R\fP\fIxmin\fP/\fIxmax\fP/\fIymin\fP/\fIymax\fP[\fB+r\fP][\fB+u\fP\fIunit\fP] (more ...)
Specify the region of interest. If no map projection is supplied we implicitly set \fB\-Jx\fP1.
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.INDENT 0.0
.TP
\fB\-Z\fP\fImin\fP[/\fImax\fP][\fB+c\fP\fIcol\fP]
Pass all records whose 3rd column (\fIz\fP; \fIcol\fP = 2) lies within the given range
or is NaN (use \fB\-s\fP to skip NaN records).
If \fImax\fP is omitted then we test if \fIz\fP equals \fImin\fP 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 \fB\-f\fP2T. To specify another column, append
\fB+c\fP\fIcol\fP, and to specify several tests just repeat the \fBZ\fP option as
many times has you have columns to test. Note: when more than one \fBZ\fP option
is given then the \fBIz\fP option cannot be used.
.UNINDENT
.INDENT 0.0
.TP
\fB\-bi\fP[\fIncols\fP][\fBt\fP] (more ...)
Select native binary input. [Default is 2 input columns].
.UNINDENT
.INDENT 0.0
.TP
\fB\-bo\fP[\fIncols\fP][\fItype\fP] (more ...)
Select native binary output. [Default is same as input].
.UNINDENT
.INDENT 0.0
.TP
\fB\-d\fP[\fBi\fP|\fBo\fP]\fInodata\fP (more ...)
Replace input columns that equal \fInodata\fP with NaN and do the reverse on output.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-e\fP[\fB~\fP]\fI"pattern"\fP \fB|\fP \fB\-e\fP[\fB~\fP]/\fIregexp\fP/[\fBi\fP] (more ...)
Only accept data records that match the given pattern.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-f\fP[\fBi\fP|\fBo\fP]\fIcolinfo\fP (more ...)
Specify data types of input and/or output columns.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-g\fP[\fBa\fP]\fBx\fP|\fBy\fP|\fBd\fP|\fBX\fP|\fBY\fP|\fBD\fP|[\fIcol\fP]\fBz\fP[+|\-]\fIgap\fP[\fBu\fP] (more ...)
Determine data gaps and line breaks.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-h\fP[\fBi\fP|\fBo\fP][\fIn\fP][\fB+c\fP][\fB+d\fP][\fB+r\fP\fIremark\fP][\fB+r\fP\fItitle\fP] (more ...)
Skip or produce header record(s).  
.UNINDENT
.INDENT 0.0
.TP
\fB\-i\fP\fIcols\fP[\fB+l\fP][\fB+s\fP\fIscale\fP][\fB+o\fP\fIoffset\fP][,\fI\&...\fP] (more ...)
Select input columns and transformations (0 is first column).
.UNINDENT
.INDENT 0.0
.TP
\fB\-o\fP\fIcols\fP[,...] (more ...)
Select output columns (0 is first column).
.UNINDENT
.INDENT 0.0
.TP
\fB\-s\fP[\fIcols\fP][\fBa\fP|\fBr\fP] (more ...)
Set handling of NaN records.
.UNINDENT
.INDENT 0.0
.TP
\fB\-:\fP[\fBi\fP|\fBo\fP] (more ...)
Swap 1st and 2nd column on input and/or output.
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.UNINDENT
.SH UNITS
.sp
For map distance unit, append \fIunit\fP \fBd\fP for arc degree, \fBm\fP for arc
minute, and \fBs\fP for arc second, or \fBe\fP for meter [Default], \fBf\fP
for foot, \fBk\fP for km, \fBM\fP for statute mile, \fBn\fP for nautical mile,
and \fBu\fP for US survey foot. By default we compute such distances using
a spherical approximation with great circles. Prepend \fB\-\fP to a
distance (or the unit is no distance is given) to perform "Flat Earth"
calculations (quicker but less accurate) or prepend \fB+\fP to perform
exact geodesic calculations (slower but more accurate).
.SH ASCII FORMAT PRECISION
.sp
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 FORMAT_DATE_OUT and
FORMAT_CLOCK_OUT, whereas general floating point values are formatted
according to FORMAT_FLOAT_OUT\&. Be aware that the format 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 (\fB\-bo\fP if available) or
specify more decimals using the FORMAT_FLOAT_OUT setting.
.sp
This note applies to ASCII output only in combination with binary or
netCDF input or the \fB\-:\fP option. See also the note below.
.SH NOTE ON PROCESSING ASCII INPUT RECORDS
.sp
Unless you are using the \fB\-:\fP option, selected ASCII input records are
copied verbatim to output. That means that options like \fB\-foT\fP and
settings 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.
.SH NOTE ON DISTANCES
.sp
If options \fB\-C\fP or \fB\-L\fP are selected then distances are Cartesian
and in user units; use \fB\-fg\fP to imply spherical distances in km and
geographical (lon, lat) coordinates. Alternatively, specify \fB\-R\fP and
\fB\-J\fP to measure projected Cartesian distances in map units (cm, inch,
or points, as determined by PROJ_LENGTH_UNIT).
.sp
This program has evolved over the years. Originally, the \fB\-R\fP and
\fB\-J\fP were mandatory in order to handle geographic data, but now there
is full support for spherical calculations. Thus, \fB\-J\fP should only be
used if you want the tests to be applied on projected data and not the
original coordinates. If \fB\-J\fP is used the distances given via \fB\-C\fP
and \fB\-L\fP are projected distances.
.SH NOTE ON SEGMENTS
.sp
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.
.SH EXAMPLES
.sp
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
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt select lonlatfile \-fg \-Cpts.txt+d300k \-Llines.txt+d100k \-Il > subset
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Here, you must specify \fB\-fg\fP so the program knows you are processing
geographical data.
.sp
To keep all points in data.txt within the specified region, except the
points on land (as determined by the high\-resolution coastlines), use
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt select data.txt \-R120/121/22/24 \-Dh \-Nk/s > subset
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To return all points in quakes.txt that are inside or on the spherical
polygon lonlatpath.txt, try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt select quakes.txt \-Flonlatpath.txt \-fg > subset1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To return all points in stations.txt that are within 5 cm of the point in
origin.txt for a certain projection, try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt select stations.txt \-Corigin.txt+d5 \-R20/50/\-10/20 \-JM20c \e
\-\-PROJ_LENGTH_UNIT=cm > subset2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To return all points in quakes.txt that are inside the grid topo.nc
where the values are nonzero, try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt select quakes.txt \-Gtopo.nc > subset2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH GSHHS INFORMATION
.sp
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 \fB\-A\fP 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 correcting 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 \fB\-A\fP); 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 database using the Douglas\-Peucker line\-simplification
algorithm. The classification of rivers and borders follow that of the
WDBII. See the GMT Cookbook and Technical Reference Appendix K for
further details.
.SH SEE ALSO
.sp
gmt,
gmt.conf,
gmtconvert,
gmtsimplify,
gmtspatial,
grdlandmask,
pscoast
.SH COPYRIGHT
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
.\" Generated by docutils manpage writer.
.