## 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)