grdselect

Make selections or determine common regions from 2-D grids, images or 3-D cubes

Synopsis

gmt grdselect source1 source2 … [ -Ai|u[+il|h|inc] ] [ -Cpointfile ] [ -Dinc ] [ -E[b] ] [ -Fpolygonfile[+i|o] ] [ -G ] [ -I[C][D][F][L][N][R][W][Z][r] ] [ -Llinefile ] [ -Mmargins ] [ -Nl|h[n] ] [ -Rregion ] [ -V[level] ] [ -W[wmin/wmax] ] [ -Z[zmin/zmax]] ] [ -fflags ] [ -hheaders ] [ -oflags ] [ -rreg ] [ --PAR=value ]

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

Description

grdselect reads several images or grids (or cubes) and skips those that fail any tests that may have been specified. It then either reports the names of the sources that passed the tests or determines the intersection or union of the regions of those sources and the range of data values inside that region. The region may be rounded and padded outwards, then reported either by its coordinates, a bounding polygon, or a -Rw/e/s/n string. Note: This module is new in GMT 6.3.0 and is considered experimental.

Required Arguments

ingrid[=ID|?varname][+bband][+ddivisor][+ninvalid][+ooffset][+sscale]

The name of one or several 2-D grid, image or 3-D cube files. Note: You cannot mix 2-D and 3-D files. Optionally, append =ID for reading a specific file format [Default is =nf] or ?varname for a specific netCDF variable [Default is the first 2-D grid found by GMT] (See full description). The following modifiers are supported:

  • +b - Select a band (for images only) [Default is 0].

  • +d - Divide data values by the given divisor [Default is 1].

  • +n - Replace data values matching invalid with NaN.

  • +o - Offset data values by the given offset [Default is 0].

  • +s - Scale data values by the given scale [Default is 1].

Note: Any offset is added after any scaling.

Optional Arguments

-Ai|u[+il|h|inc]

Append either directive i for intersection or u for union. We then report either the common region for all the data sources that passed the tests (if any) or the maximum extent of all the sources that passed the tests. Optionally, append modifier +i and specify a rounding increment to be applied to the final region: Specify l for the lowest increment of all passed data sources, h for the highest increment, or inc to set a specific increment. If -A is not used then we just list the names of the sources that passed (or not; see -I) any tests selected from -C -D -F -L -N -R -W -Z -R.

-Cpointfile

Specify a multisegment point file. A data source must contain at least one point from pointfile to pass [Default is to not consider point inclusions]. Note: If data source is a 3-D cube then we also check if pointfile has z-coordinates and if the 3-D point is inside the cube [Default is to only check in map view].

-Dinc

Only pass data sources whose increments match the given increments [Default does not consider the increments when passing or skipping data sources].

-E[b]

Formats an output data record using tab-separated fields on a single line. The columns are w e s n {b t} v0 v1. The data in braces only apply if grdselect is used with 3-D data cubes [Default outputs a single -Rw/e/s/n{/b/t} string]. Alternatively, append directive b to output the region’s closed polygon. Note: The v0 v1 range reflects the full range of all data nodes that lie inside the final region after any rounding or padding have taken place. Also, if the grids have different increments then a rounding increment is required to be set via -A+i unless -Eb is used.

-Fpolygonfile[+i|o]

Specify a multisegment closed polygon file. A data source must partially or fully overlap with at least one polygon in polygonfile to pass [Default is to not consider polygonal areas]. To only find data sources that are fully inside or outside the polygon append +i or +o, respectively. Note: If data source is a cube then we ignore the z-dimension (i.e., we only check for overlap in map view).

-G

Force (possible) download of all tiles of any tiled global remote grids given in order to report the requested information [Default is to refuse to give the information for tiled grids].

-I[C][D][F][L][N][R][W][Z][r]

Reverses the sense of the test for each of the options that match the specified code(s):

  • C - select data sources not containing any of the points specified in -C.

  • D - select data sources not having the specified increment in -D.

  • F - select data sources not overlapping with any of the polygons specified in -F.

  • L - select data sources not traversed by any of the lines specified in -L.

  • N - select data sources failing the NaN criterion in -N.

  • R - select data sources not having any overlap with the region set in -R.

  • W - select data sources whose data range do not overlap the range specified by -W.

  • Z - select cubes whose z-dimension range do not overlap the range specified by -Z.

  • r - select data sources not having the specified registration specified by -R.

If no argument is given then we reverse all the tests, i.e, the same as -ICDFLNRWZr.

-Llinefile

Specify a multisegment line file. A data source must be traversed by at least one line in linefile to pass [Default is no line traversing considered]. Note: If data source is a cube then we ignore the z-dimension (i.e., we only check for crossings in map view).

-Mmargins

Extend the region determined via -A by the given margins. These can be specified as a single value (use the same margin on all sides), a pair of values separated by slashes (set separate x and y margins), or the full set of four slash-separated margins (set separate west, east, south, and north margins) [no region padding]. For geographic (lon/lat) grids you may use units d, m, or s as needed.

-Nl|h[n]

Only pass data sources that have a total number of NaNs that is either lower or higher than n [Default is 0]. Note: Cannot be used with images.

-Rxmin/xmax/ymin/ymax[+r][+uunit]

Specify the region of interest. Using the -R option will in essence supply another region that will be included in the computation via -A, as well as limit the reading to that subset. For 3-D cubes you must also append limits in the z dimension. (See full description) (See cookbook information).

-W[wmin]/[wmax]

Only pass data sources whose data range overlaps with the specified range. If wmin is not given it defaults to -infinity, while if wmax is not given it defaults to +infinity. Note: Cannot be used with images.

-Z[zmin]/[zmax]

Only pass 3-D cubes whose z-dimension range overlaps with the specified range. If zmin is not given it defaults to -infinity, while if zmax is not given it defaults to +infinity.

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

-f[i|o]colinfo (more …)

Specify data types of input and/or output columns.

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …)

Skip or produce header record(s).

-ocols[,…][,t[word]] (more …)

Select output columns (0 is first column; t is trailing text, append word to write one word only).

-r[g|p]

Only pass data sources that have the same registration as that specified [Ignore registration when determining which data sources to pass or skip].

-^ or just -

Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Examples

To find the extended region (union) of all the grids given, plus a padding of 2 degrees, try:

gmt grdcut @earth_relief_01d -R1/3/1/3 -Gsubset1.nc
gmt grdcut @earth_relief_01d -R2/5/2/5 -Gsubset2.nc
gmt grdselect *.nc -Au -M2

To find the common region (intersection) that all the grids share, try:

gmt grdselect *.nc -Ai

To find the common region (intersection) that all the grids share but extend it by 2 degrees and then write the bounding polygon, try:

gmt grdselect *.nc -Ai -M2 -Eb > wesn_polygon.txt

To list all the data sources that have more than 10 NaN nodes and are pixel registered, try:

gmt grdselect *.nc -Nh10 -rp

To list all the grids that are entirely included by the polygon in wesn_polygon.txt, try:

gmt grdselect *.nc -Fwesn_polygon.txt+i

See Also

gmt, gmtselect, grd2xyz, grdedit, grdinfo