manpagez: man pages & more
man gmtselect(1)
Home | html | info | man
gmtselect(1)                          GMT                         gmtselect(1)




NAME

       gmtselect  - Select data table subsets based on multiple spatial crite-
       ria


SYNOPSIS

       gmtselect             [             table              ]              [
       -Amin_area[/min_level/max_level][+ag|i|s|S][+r|l][ppercent]     ]     [
       -Cpointfile+ddist[unit] ] [  -Dresolution[+] ] [  -E[fn] ]  [   -Fpoly-
       gonfile ] [  -Ggridmask ] [  -I[cfglrsz] ] [  -Jparameters ] [  -Lline-
       file+ddist[unit][+p]  ]   [    -Nmaskvalues   ]   [    -Rregion   ]   [
       -Zmin[/max][+ccol]  ] [  -V[level] ] [ -bbinary ] [ -dnodata ] [ -ereg-
       exp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [  -oflags  ]  [
       -:[i|o] ]

       Note:  No  space  is allowed between the option flag and the associated
       arguments.


DESCRIPTION

       gmtselect is a filter that reads (x, y) or (longitude, latitude)  posi-
       tions  from the first 2 columns of infiles [or standard input] and uses
       a combination of 1-7 criteria to pass or reject  the  records.  Records
       can  be selected based on whether or not they are 1) inside a rectangu-
       lar region (-R [and -J]), 2) within dist km of any point in  pointfile,
       3)  within  dist km of any line in linefile, 4) inside one of the poly-
       gons in the polygonfile, 5)  inside  geographical  features  (based  on
       coastlines), 6) has z-values within a given range, or 7) inside bins of
       a grid mask whose nodes are non-zero. 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 (y,x) or (latitude,longitude) files.  Note: If
       no projection information is used then you must supply -fg to tell gmt-
       select that your data are geographical.


REQUIRED ARGUMENTS

       None


OPTIONAL ARGUMENTS

       table  One or more ASCII (or binary, see -bi[ncols][type])  data  table
              file(s) holding a number of data columns. If no tables are given
              then we read from standard input.

       -Amin_area[/min_level/max_level][+ag|i|s|S][+r|l][+ppercent]
              Features with an area smaller than min_area in km^2 or of  hier-
              archical  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.  By default (+ai)
              we select the ice shelf boundary as the  coastline  for  Antarc-
              tica;  append  +ag  to  instead select the ice grounding line as
              coastline.  For expert users who wish to print their own Antarc-
              tica  coastline and islands via psxy you can use +as to skip all
              GSHHG features below 60S or +aS to  instead  skip  all  features
              north  of  60S.   Finally,  append +ppercent to exclude polygons
              whose percentage area of the corresponding full-resolution  fea-
              ture  is less than percent. See GSHHG INFORMATION below for more
              details. Ignored unless -N is set.

       -Cpointfile+ddist[unit]
              Pass all records whose location is within dist  of  any  of  the
              points in the ASCII file pointfile. If dist is zero then the 3rd
              column of pointfile must have each pointas individual radius  of
              influence.  Distances  are  Cartesian and in user units; specify
              -fg to indicate spherical distances and append a  distance  unit
              (see  UNITS).  Alternatively,  if  -R  and -J are used then geo-
              graphic coordinates are projected to  map  coordinates  (in  cm,
              inch,  or  points,  as  determined  by  PROJ_LENGTH_UNIT) before
              Cartesian distances are compared to dist.

       -Dresolution[+]
              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]. Append (+) to automatically select a lower reso-
              lution 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.

       -E[fn] Specify  how points exactly on a polygon boundary should be con-
              sidered. By default, such points are considered to be inside the
              polygon.  Append  n  and/or f to change this behavior for the -F
              and -N options, respectively, so that boundary points  are  con-
              sidered to be outside.

       -Fpolygonfile
              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 sepa-
              rated by 180 degrees or more in longitude. Note that polygonfile
              must be in ASCII regardless of whether -bi is used.

       -Ggridmask

              Pass  all  locations  that are inside the valid data area of the
              grid gridmask.
                     Nodes that are outside are either NaN or zero.

       -I[cflrsz]
              Reverses  the  sense of the test for each of the criteria speci-
              fied:

              c select records NOT inside any pointas circle of influence.

              f select records NOT inside any of the polygons.

              g will pass records inside the cells with z equal  zero  of  the
              grid mask in -G.

              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.

       -Jparameters (more a|)
              Select map projection.

       -Llinefile+ddist[unit][+p]
              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 we will scan each sub-header in the linefile
              for an embedded -Ddist setting that sets each lineas  individual
              distance value. Distances are Cartesian and in user units; spec-
              ify -fg to indicate spherical distances append a  distance  unit
              (see  UNITS).  Alternatively,  if  -R  and -J are used then geo-
              graphic coordinates are projected to  map  coordinates  (in  cm,
              inch,  m,  or  points, as determined by PROJ_LENGTH_UNIT) before
              Cartesian distances are compared to dist. Append  +p  to  ensure
              only  points  whose  orthogonal  projections  onto  the  nearest
              line-segment fall within the segments endpoints [Default consid-
              ers points abeyonda the lineas endpoints.

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

              [Default  is  s/k/s/k/s  (i.e., s/k), which passes all points on
              dry land].

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
              Specify the region of interest. If no map projection is supplied
              we implicitly set -Jx1.

       -V[level] (more a|)
              Select verbosity level [c].

       -Zmin[/max][+ccol]
              Pass  all  records whose 3rd column (z; col = 2) lies within the
              given range or is NaN (use -s to skip NaN records).  If  max  is
              omitted  then  we test if z equals min instead.  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  -f2T.  To  specify  another  column,  append
              +ccol,  and to specify several tests just repeat the Z option as
              many times has you have columns to test. Note:  when  more  than
              one Z option is given then the Iz option cannot be used.

       -bi[ncols][t] (more a|)
              Select native binary input. [Default is 2 input columns].

       -bo[ncols][type] (more a|)
              Select native binary output. [Default is same as input].

       -d[i|o]nodata (more a|)
              Replace  input  columns  that  equal  nodata with NaN and do the
              reverse on output.

       -e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
              Only accept data records that match the given pattern.

       -f[i|o]colinfo (more a|)
              Specify data types of input and/or output columns.

       -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more a|)
              Determine data gaps and line breaks.

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
              Skip or produce header record(s).

       -icols[+l][+sscale][+ooffset][,^<i>a|] (more a|)
              Select input columns and transformations (0 is first column).

       -ocols[,a|] (more a|)
              Select output columns (0 is first column).

       -s[cols][a|r] (more a|)
              Set handling of NaN records.

       -:[i|o] (more a|)
              Swap 1st and 2nd column on input and/or output.

       -^ or just -
              Print a short message about the  syntax  of  the  command,  then
              exits (NOTE: on Windows just use -).

       -+ or just +
              Print  an extensive usage (help) message, including the explana-
              tion of any module-specific  option  (but  not  the  GMT  common
              options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation
              of all options, then exits.


UNITS

       For map distance unit, append unit d for arc degree, m for arc  minute,
       and s for arc second, or e for meter [Default], f for foot, k for km, M
       for statute mile, n for nautical mile, and u for  US  survey  foot.  By
       default  we compute such distances using a spherical approximation with
       great circles. Prepend - to a distance (or the unit is no  distance  is
       given) to perform aFlat Eartha calculations (quicker but less accurate)
       or prepend + to perform exact geodesic calculations  (slower  but  more
       accurate).


ASCII FORMAT PRECISION

       The ASCII output formats of numerical data are controlled by parameters
       in your gmt.conf file. Longitude and latitude are  formatted  according
       to   FORMAT_GEO_OUT,  absolute  time  is  under  the  control  of  FOR-
       MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point  val-
       ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for-
       mat in effect can lead to loss of precision in ASCII 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 FORMAT_FLOAT_OUT set-
       ting.

       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  set-
       tings like FORMAT_FLOAT_OUT and FORMAT_GEO_OUT 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, or points, as
       determined by PROJ_LENGTH_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  pro-
       jected distances.


NOTE ON SEGMENTS

       Segment  headers in the input files are copied to output if one or more
       records from a segment passes the test. Selection is always done  point
       by  point,  not by segment.  That means only points from a segment that
       pass the test will be included in the output.  If you wish to clip  the
       lines  and include the new boundary points at the segment ends you must
       use gmtspatial instead.


EXAMPLES

       To extract the subset of data set that is within 300 km of any  of  the
       points  in  pts.txt  but  more  than  100  km  away  from  the lines in
       lines.txt, run

              gmt select lonlatfile -fg -Cpts.txt+d300k -Llines.txt+d100k -Il > subset

       Here, you must specify -fg so the program knows you are processing geo-
       graphical data.

       To  keep all points in data.txt within the specified region, except the
       points on land (as determined by the high-resolution coastlines), use

              gmt select data.txt -R120/121/22/24 -Dh -Nk/s > subset

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

              gmt select quakes.txt -Flonlatpath.txt -fg > subset1

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

              gmt select stations.txt -Corigin.txt+d5 -R20/50/-10/20 -JM20c \
              --PROJ_LENGTH_UNIT=cm > subset2

       To return all points in quakes.txt that are  inside  the  grid  topo.nc
       where the values are nonzero, try

              gmt select quakes.txt -Gtopo.nc > subset2


GSHHS INFORMATION

       The coastline database is GSHHG (formerly GSHHS) which is compiled from
       three sources:  World Vector Shorelines (WVS), CIA World Data  Bank  II
       (WDBII),  and Atlas of the Cryosphere (AC, for Antarctica only).  Apart
       from Antarctica, 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.
       The Antarctica coastlines come in two flavors: ice-front  or  grounding
       line, selectable via the -A option.  Much processing has taken place to
       convert WVS, WDBII, and AC data into usable form  for  GMT:  assembling
       closed  polygons  from line segments, checking for duplicates, and cor-
       recting 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  data-
       base using the Douglas-Peucker line-simplification algorithm. The clas-
       sification of rivers and borders follow that of the WDBII. See the  GMT
       Cookbook and Technical Reference Appendix K for further details.


SEE ALSO

       gmt(1), gmt.conf(5), gmtconvert(1), gmtsimplify(1), gmtspatial(1),
       grdlandmask(1), pscoast(1)


COPYRIGHT

       2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe



5.4.2                            Jun 24, 2017                     gmtselect(1)

gmt5 5.4.2 - Generated Wed Jun 28 16:33:22 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.