## 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  ]  [  -L[dist/linefile] ] [ -M[flag] ] [
           -Nmaskvalues[o] ] [ -Rwest/east/south/north[r] ]  [  -V  ]  [  -:  ]  [
           -bi[s][n] ] [ -bo[s][n] ]

## 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-5  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,  and  5)  inside  geographical features (based on
           coastlines).  The sense of the tests can be reversed for each of  these
           5 criteria by using the -I option.  See option -: on how to read (lati-
           tude,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 km of any of  the
                  points  in ptfile. If dist is zero then the 3rd column of ptfile
                  must have each point’s individual radius of influence.   Prepend
                  f to indicate you want approximate flat’ earth distance calcula-
                  tions (faster) 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 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.

           -H     Input file(s) has Header record(s). Number of header records can
                  be  changed  by  editing  your  .gmtdefaults  file. If used, GMT
                  default is 1 header record.

           -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
                  -A, -D, -N.

           -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 .gmtdefaults, but this
                  can be overridden on the command line by appending the c, i,  or
                  m to the scale/width value.

                  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]]  (Linear,  log,  and  power
                  scaling)
                  More details can be found in the psbasemap manpages.

           -L     Pass  all records whose location is within dist km of any of the
                  line segments in the 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.’  If  no  arguments
                  are  given,  it  means instead that the x column contains longi-
                  tudes, which may differ from the region in -R by [multiples  of]
                  360 degrees [Default assumes no periodicity]

           -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 or kkept 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     west, east, south, and north specify the Region of interest.  To
                  specify boundaries in degrees and minutes [and seconds], use the
                  dd:mm[:ss] format. Append r if lower left and  upper  right  map
                  coordinates  are given instead of wesn.  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/output. [Default  is  (longitude,latitude)].   Applies  to
                  geographic coordinates only.

           -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].

           -O     Selects  Overlay  plot mode [Default initializes a new plot sys-
                  tem].

## 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,
           try

           gmtselect lonlatfile -Jd1d -C300/pts.d -L100/lines.d -Il > subset

           Here, you must specify a mapprojection 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 except
           those on land, as determined by the high-resolution coastlines, try

           gmtselect data.d -R120/121/22/24 -Dh -Ns/k > subset

## SEE ALSO

           gmtdefaults(l), gmt(l), grdlandmask(l), pscoast(l)

    GMT3.4.6                          1 Jan 2005                      GMTSELECT(l)