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)

Man(1) output converted with man2html