NAME
gmtselect - Select data subsets based on multiple spatial criteria
SYNOPSIS
gmtselect [ infiles ] [ -Amin_area[/min_level/max_level] ] [
-C[f]dist/ptfile ] [ -Dresolution ] [ -Fpolygonfile ] [ -H[nrec] ] [
-I[cflrs] ] [ -Jparameters ] [ -Ldist/linefile ] [ -M[flag] ] [
-Nmaskvalues[o] ] [ -Rwest/east/south/north[r] ] [ -V ] [ -Zmin/max] ]
[ -: ] [ -bi[s][n] ] [ -bo[s][n] ] [ -f[i|o]colinfo ]
DESCRIPTION
gmtselect 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.
No space between the option flag and the associated arguments.
Use upper case for the option flags and lower case for modifiers.
infiles
ASCII (or binary, see-b) data file(s) to be operated on. If not
given, standard input is read.
OPTIONS
-A Ignored unless -N is set. Geographical features with an area
smaller than min_area in km^2 or of hierarchical level that is
lower than min_level or higher than max_level will be ignored
[Default is 0/4 (all features)]. See DATABASE INFORMATION in the
pscoast man-pages for more details.
-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 in user units; specify -fg or a map
projection to indicate distances in km. Prepend f to indicate
you want approximate flat earth distance calculations (faster)
rather than exact great circle calculations (slower).
-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]. 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 ASCII file polygonfile.
-H Input file(s) has Header record(s). Number of header records can
be changed by editing your .gmtdefaults4 file. If used, GMT
default is 1 header record. Use -Hi if only input data should
have header records [Default will write out header records if
the input data have them].
-I Reverses the sense of the test for each of the criteria speci-
fied:
c select records NOT inside any point’s circle of
influence.
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
-A, -D, -N.
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. For map height, max dimension, or min
dimension, append h, +, or - to the width, respectively.
CYLINDRICAL PROJECTIONS:
-Jclon0/lat0/scale (Cassini)
-Jjlon0/scale (Miller)
-Jmscale (Mercator - Greenwich and Equator as origin)
-Jmlon0/lat0/scale (Mercator - Give meridian and standard paral-
lel)
-Joalon0/lat0/azimuth/scale (Oblique Mercator - point and
azimuth)
-Joblon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
-Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and
pole)
-Jqlon0/scale (Equidistant Cylindrical Projection (Plate Car-
ree))
-Jtlon0/scale (TM - Transverse Mercator, with Equator as y = 0)
-Jtlon0/lat0/scale (TM - Transverse Mercator, set origin)
-Juzone/scale (UTM - Universal Transverse Mercator)
-Jylon0/lats/scale (Basic Cylindrical Projection)
AZIMUTHAL PROJECTIONS:
-Jalon0/lat0/scale (Lambert).
-Jelon0/lat0/scale (Equidistant).
-Jflon0/lat0/horizon/scale (Gnomonic).
-Jglon0/lat0/scale (Orthographic).
-Jslon0/lat0/[slat/]scale (General Stereographic)
CONIC PROJECTIONS:
-Jblon0/lat0/lat1/lat2/scale (Albers)
-Jdlon0/lat0/lat1/lat2/scale (Equidistant)
-Jllon0/lat0/lat1/lat2/scale (Lambert)
MISCELLANEOUS PROJECTIONS:
-Jhlon0/scale (Hammer)
-Jilon0/scale (Sinusoidal)
-Jk[f|s]lon0/scale (Eckert IV (f) and VI (s))
-Jnlon0/scale (Robinson)
-Jrlon0/scale (Winkel Tripel)
-Jvlon0/scale (Van der Grinten)
-Jwlon0/scale (Mollweide)
NON-GEOGRAPHICAL PROJECTIONS:
-Jp[a]scale[/origin] (polar (theta,r) coordinates, optional a
for azimuths and offset theta [0])
-Jxx-scale[l|ppow][/y-scale[l|ppow]][d] (Linear, log, and power
scaling)
More details can be found in the psbasemap man pages.
-L Pass all records whose location is within dist of any of the
line segments in the multiple-segment ascii 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 in user units; specify -fg or a map projection to
indicate distances in km.
-M Multiple segment file. Segments are separated by a record whose
first character is flag. [Default is ’>’].
-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].
-Z Pass all records whose 3rd colum (z) lies within the given
range. Input file must have at least three columns. To indicate
no limit on min or max, specify a hyphen (-).
-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 wesn. The
two shorthands -Rg -Rd stand for global domain (0/360 or
-180/+180 in longitude respectively, with -90/+90 in latitude).
For calendar time coordinates you may either give relative time
(relative to the selected TIME_EPOCH and in the selected
TIME_UNIT; append t to -JX|x), or 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 delimiters and their
type and positions must be as indicated (however, input/output
and plotting formats are flexible). If no map projection is
supplied we implicitly set -Jx1.
-V Selects verbose mode, which will send progress reports to stderr
[Default runs "silently"].
-: 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
double]. Append n for the number of columns in the binary
file(s).
[Default is 2 input columns].
-bo Selects binary output. Append s for single precision [Default is
double]. Append n for the number of columns in the binary
file(s).
-f Special formatting of input and output columns (time or geo-
graphical data) Specify i(nput) or o(utput) [Default is both
input and output]. Give one or more columns (or column ranges)
separated by commas. Append T (Absolute calendar time), t (time
relative to chosen TIME_EPOCH), x (longitude), y (latitude), g
(geographic coordinate), or f (floating point) to each column or
column range item.
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 -Jd1d -C300/pts.d -L100/lines.d -Il > subset
Here, you must specify a map projection so that knows you are giving it
geographical 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 -R120/121/22/24 -Dh -Ns/k > subset
SEE ALSO
gmtdefaults(l), gmt(l), grdlandmask(l), pscoast(l)
GMT4.0 1 Oct 2004 GMTSELECT(l)
Man(1) output converted with
man2html