Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       gmtselect - Select data subsets based on multiple spatial criteria

SYNOPSIS

       gmtselect   [   infiles   ]   [   -Amin_area[/min_level/max_level][+r|l][ppercent]   ]   [
       -C[f]dist/ptfile ] [ -Dresolution[+] ] [ -Fpolygonfile ] [ -H[i][nrec] ] [ -I[cflrsz] ]  [
       -Jparameters ] [ -L[p]dist/linefile ] [ -Nmaskvalues[o] ] [ -Rwest/east/south/north[r] ] [
       -V ] [ -Zmin/max] ] [ -:[i|o] ] [ -b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ -f[i|o]colinfo  ]
       [ -m[i|o][flag] ]

DESCRIPTION

       gmtselect  is a filter that reads (longitude, latitude) positions from the first 2 columns
       of infiles [or standard input] and uses a combination 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 coastlines), 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.

       infiles
              ASCII (or binary, see -b) data file(s) to be operated on.  If not  given,  standard
              input is read.

OPTIONS

       No space between the option flag and the associated arguments.

       -A     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 not be  plotted  [Default  is
              0/0/4  (all  features)].   Level  2  (lakes)  contains regular lakes and wide river
              bodies which we normally include as lakes; append +r to just get river-lakes or  +l
              to  just  get  regular  lakes  (requires  GSHHS  2.0.1 or higher).  Finally, append
              +ppercent to exclude polygons whose percentage  area  of  the  corresponding  full-
              resolution  feature is less than percent (requires GSHHS 2.0 or higher).  See GSHHS
              INFORMATION below for more details.  Ignored unless -N is set.

       -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 Cartesian and in user units; specify
              -fg to indicate spherical distances in km.  Use -Cf to indicate you want flat Earth
              distances (quicker but approximate) rather  than  geodesic  distances  (slower  but
              exact).   If  ELLIPSOID is spherical then geodesics become great circles (faster to
              compute than geodesic).  Alternatively, if -R  and  -J  are  used  then  geographic
              coordinates  are  projected  to  map  coordinates  (in  cm,  inch, m, or points, as
              determined by MEASURE_UNIT) before Cartesian distances are compared to dist.

       -D     Ignored unless -N is set.  Selects the resolution of the coastline 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].  Append + to automatically select  a  lower
              resolution  should  the  one requested not be available [abort if not found].  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 file polygonfile.  For spherical polygons (lon, lat), make sure no
              consecutive  points  are  separated by 180 degrees or more in longitude.  Note that
              polygonfile must be in ASCII regardless of whether -b is used.

       -H     Input file(s) has header record(s).  If used, the default number of header  records
              is  N_HEADER_RECS.   Use -Hi if only input data should have header records [Default
              will write out header records if the input data have them]. Blank lines  and  lines
              starting with # are always skipped.

       -I     Reverses the sense of the test for each of the criteria specified:
                   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 -N (and -A, -D).
                   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.  When central meridian is optional, default  is  center
              of  longitude  range  on -R option.  Default standard parallel is the equator.  For
              map height, max dimension, or min dimension, append  h,  +,  or  -  to  the  width,
              respectively.
              More details can be found in the psbasemap man pages.

              CYLINDRICAL PROJECTIONS:

              -Jclon0/lat0/scale (Cassini)
              -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
              -Jj[lon0/]scale (Miller)
              -Jm[lon0/[lat0/]]scale (Mercator)
              -Jmlon0/lat0/scale (Mercator - Give meridian and standard parallel)
              -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and azimuth)
              -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
              -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and pole)
              -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
              -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
              -Juzone/scale (UTM - Universal Transverse Mercator)
              -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)

              CONIC PROJECTIONS:

              -Jblon0/lat0/lat1/lat2/scale (Albers)
              -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
              -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
              -Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)

              AZIMUTHAL PROJECTIONS:

              -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
              -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
              -Jflon0/lat0[/horizon]/scale (Gnomonic)
              -Jglon0/lat0[/horizon]/scale (Orthographic)
              -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale (General Perspective).
              -Jslon0/lat0[/horizon]/scale (General Stereographic)

              MISCELLANEOUS PROJECTIONS:

              -Jh[lon0/]scale (Hammer)
              -Ji[lon0/]scale (Sinusoidal)
              -Jkf[lon0/]scale (Eckert IV)
              -Jk[s][lon0/]scale (Eckert VI)
              -Jn[lon0/]scale (Robinson)
              -Jr[lon0/]scale (Winkel Tripel)
              -Jv[lon0/]scale (Van der Grinten)
              -Jw[lon0/]scale (Mollweide)

              NON-GEOGRAPHICAL PROJECTIONS:

              -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
              -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log, and power scaling)

       -L     Pass  all  records whose location is within dist of any of the line segments in the
              ASCII 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.
              Distances are Cartesian and in  user  units;  specify  -fg  to  indicate  spherical
              distances  in  km.   If  ELLIPSOID is spherical then geodesics become great circles
              (faster to compute than geodesic).  Alternatively, if  -R  and  -J  are  used  then
              geographic coordinates are projected to map coordinates (in cm, inch, m, or points,
              as determined by MEASURE_UNIT) before Cartesian distances  are  compared  to  dist.
              Use  -Lp  to ensure only points whose orthogonal projections onto the nearest line-
              segment fall within the segments endpoints [Default considers points  "beyond"  the
              line's endpoints.

       -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  considered  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     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 w/e/s/n.  The two shorthands
              -Rg and -Rd stand for global domain (0/360 and -180/+180 in longitude respectively,
              with  -90/+90  in  latitude).   Alternatively, specify the name of an existing grid
              file and the -R settings (and grid spacing, if  applicable)  are  copied  from  the
              grid.   For  calendar  time  coordinates  you  may  either  give  (a) relative time
              (relative to the selected TIME_EPOCH and in the selected  TIME_UNIT;  append  t  to
              -JX|x),  or  (b)  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 exactly as indicated
              (however, input, output and plot formats are customizable; see gmtdefaults).  If no
              map  projection is supplied we implicitly set -Jx 1. Note: only supply -J when your
              -R is indicating a rectangular  region  in  the  projected  coordinates  (i.e.,  an
              oblique projection).

       -V     Selects  verbose  mode,  which  will  send progress reports to stderr [Default runs
              "silently"].

       -Z     Pass all records whose 3rd column (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
              (-).  If your 3rd column is absolute time then remember to supply -f 2T.

       -:     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  d  (double)].
              Uppercase  S or D will force byte-swapping.  Optionally, append ncol, the number of
              columns in your binary input file if it exceeds the columns needed by the  program.
              Or  append  c  if  the  input  file  is netCDF. Optionally, append var1/var2/... to
              specify the variables to be read.  [Default is 2 input columns].

       -bo    Selects binary output.  Append s for single  precision  [Default  is  d  (double)].
              Uppercase  S or D will force byte-swapping.  Optionally, append ncol, the number of
              desired columns in your binary output file.  [Default is same as input].

       -f     Special formatting of input and/or output  columns  (time  or  geographical  data).
              Specify  i  or  o  to  make  this apply only to input or output [Default applies to
              both].  Give one or more columns (or column ranges) separated by commas.  Append  T
              (absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x
              (longitude), y (latitude), or f (floating point) to each  column  or  column  range
              item.  Shorthand -f[i|o]g means -f[i|o]0x,1y (geographic coordinates).

       -m     Multiple  segment  file(s).  Segments are separated by a special record.  For ASCII
              files the first character must be flag [Default is  '>'].   For  binary  files  all
              fields  must  be  NaN  and -b must set the number of output columns explicitly.  By
              default the -m setting applies to both input and output.  Use -mi and -mo  to  give
              separate  settings  to  input  and  output.   The  -m option make sure that segment
              headers in the input files are copied to output, but it has no effect on  the  data
              selection. Selection is always done point by point, not by segment.

ASCII FORMAT PRECISION

       The  ASCII  output  formats  of  numerical  data  are  controlled  by  parameters  in your
       .gmtdefaults4   file.    Longitude   and   latitude    are    formatted    according    to
       OUTPUT_DEGREE_FORMAT,  whereas other values are formatted according to D_FORMAT.  Be aware
       that the format in effect can lead to loss of precision in the output, which can  lead  to
       various problems downstream.  If you find the output is not written with enough precision,
       consider switching to binary output (-bo if available) or specify more decimals using  the
       D_FORMAT setting.
       This  note  applies to ASCII output only in combination with binary or netCDF input or the
       -: option.  See also the note below.

NOTE ON PROCESSING ASCII INPUT RECORDS

       Unless you are using the -: option, selected ASCII input records are  copied  verbatim  to
       output.    That   means   that   options   like   -foT  and  settings  like  D_FORMAT  and
       OUTPUT_DEGREE_FORMAT will not have any effect on the output.  On the other hand, it allows
       selecting  records  with  diverse  content,  including  character  strings, quoted or not,
       comments, and other non-numerical content.

NOTE ON DISTANCES

       If options -C or -L are selected then distances are Cartesian and in user units;  use  -fg
       to   imply   spherical   distances   in   km  and  geographical  (lon,  lat)  coordinates.
       Alternatively, specify -R and -J to measure projected Cartesian  distances  in  map  units
       (cm, inch, m, or points, as determined by MEASURE_UNIT).
       This  program  has  evolved  over  the years.  Originally, the -R and -J were mandatory in
       order to handle geographic data, but now there is full support for spherical calculations.
       Thus, -J should only be used if you want the tests to be applied on projected data and not
       the original coordinates.  If -J is used the distances given via -C and -L  are  projected
       distances.

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 -fg -C 300/pts.d -L 100/lines.d -Il > subset

       Here, you must specify -fg so the program  knows  you  are  processing  geographical  data
       (otherwise 300 would be interpreted as Cartesian distance 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 -R 120/121/22/24 -Dh -Nk/s > subset

       To return all points in quakes.d that are inside the spherical polygon lonlatpath.d, try

       gmtselect quakes.d -F lonlatpath.d -fg > subset1

       To return all points in stations.d that are within 5 cm of the point  in  origin.d  for  a
       certain projection, try

       gmtselect stations.d -F origin.d -R 20/50/-10/20 -JM 20c > subset2

GSHHS INFORMATION

       The  coastline  database  is  GSHHS  which  is  compiled  from  two  sources: World Vector
       Shorelines (WVS) and CIA World Data Bank II (WDBII).  In particular, all level-1  polygons
       (ocean-land  boundary)  are  derived  from  the  more  accurate WVS while all higher level
       polygons (level 2-4, representing land/lake, lake/island-in-lake, and island-in-lake/lake-
       in-island-in-lake  boundaries)  are  taken from WDBII.  Much processing has taken place to
       convert WVS and WDBII data into usable form for GMT: assembling closed polygons from  line
       segments,  checking  for  duplicates,  and correcting for crossings between polygons.  The
       area of each polygon has been determined so that the user may choose not to draw  features
       smaller than a minimum area (see -A); one may also limit the highest hierarchical level of
       polygons to be included (4 is the maximum).  The 4 lower-resolution databases were derived
       from the full resolution database using the Douglas-Peucker line-simplification algorithm.
       The classification of rivers and borders follow that of the WDBII.  See the  GMT  Cookbook
       and Technical Reference Appendix K for further details.

SEE ALSO

       gmtdefaults(1), GMT(1), grdlandmask(1), pscoast(1)