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