.. index:: ! grdinfo .. include:: module_core_purpose.rst_ ******* grdinfo ******* |grdinfo_purpose| Synopsis -------- .. include:: common_SYN_OPTs.rst_ **gmt grdinfo** *ingrid* [ |-C|\ [**n**\|\ **t**\] ] [ |-D|\ [*xoff*\ [/*yoff*]][**+i**] ] [ |-E|\ [**x**\|\ **y**][**+l**\|\ **L**\|\ **u**\|\ **U**] ] [ |-F| ] [ |-G| ] [ |-I|\ [*dx*\ [/*dy*]\|\ **b**\|\ **i**\|\ **o**\|\ **r**] ] [ |-L|\ [**0**\|\ **1**\|\ **2**\|\ **p**\|\ **a**] ] [ |-M|\ [**c**\|\ **f**] ] [ |SYN_OPT-R| ] [ |-T|\ [*dv*]\ [**+a**\ [*alpha*]]\ [**+s**] ] [ |SYN_OPT-V| ] [ |SYN_OPT-f| ] [ |SYN_OPT-h| ] [ |SYN_OPT-o| ] [ |SYN_OPT--| ] |No-spaces| Description ----------- **grdinfo** reads a 2-D binary grid file and reports metadata and various statistics for the data (*v*) and coordinates (*x*,\ *y*) in a grid (or *x*,\ *y*,\ *z* for a 3-D cube). The output information may report the minimum/maximum values for *v* and the coordinates, where the min/max of *v* occur, the spatial increments, and the number of nodes in each dimension, and [optionally] the mean, standard deviation, and/or the median, median absolute deviation (MAD) of *v*, and/or the mode (Least Median of Squares; LMS), LMS scale of *v*, and number of nodes set to NaN. We also report if the grid is pixel- or gridline-registered and if it is a Cartesian or Geographic data set (based on metadata in the file). We can also report information for 3-D netCDF data cubes, but note that data cubes are not compatible with options |-D|, |-E|, |-F|, and |-I|\ **b**. Required Arguments ------------------ .. |Add_ingrid| replace:: The name of one or several 2-D grid or 3-D cube files. **Note**: You cannot mix 2-D and 3-D files. .. include:: explain_grd_inout.rst_ :start-after: ingrid-syntax-begins :end-before: ingrid-syntax-ends Optional Arguments ------------------ .. _-C: **-C**\ [**n**\|\ **t**\] Formats the report using tab-separated fields on a single line. The output is: *name w e s n {b t} v0 v1 dx dy {dz} nx ny {nz}* [*x0 y0 {z0} x1 y1 {z1}*] [*med scale*] [*mean std rms*] [*n\_nan*] *registration gtype* The data in brackets are output only if the corresponding options |-M| (with no directive), |-L|\ **1**, and |-L|\ **2** are used, respectively, while the data in braces only apply if used with 3-D data cubes. Use |-C|\ **t** to place file *name* at the end of the output record or |-C|\ **n** to only output numerical columns. The *registration* is either 0 (gridline) or 1 (pixel), while *gtype* is either 0 (Cartesian) or 1 (geographic). If the |-I| option is used, the output format is instead *NF w e s n {b t} v0 v1*, where *NF* is the total number of files read and *w e s n {b t}* are rounded off (see |-I|). .. _-D: **-D**\ [*xoff*\ [/*yoff*]][**+i**] Divide a single grid's domain (or the |-R| domain, if no grid given) into tiles of size *dx* times *dy* (set via |-I|). You can specify overlap between tiles by appending *xoff*\ [/*yoff*]. If the single grid is given you may use the modifier **+i** to ignore tiles that have no data within each tile subregion. Default output is text region strings. Use |-C| to instead report four columns with *xmin xmax ymin ymax* per tile, or use |-C|\ **t** to also have the region string appended as trailing text. .. _-E: **-E**\ [**x**\|\ **y**][**+l**\|\ **L**\|\ **u**\|\ **U**] Report the extreme values found on a per column (|-E|\ **x**) or per row (|-E|\ **y**) basis. By default, we look for the global maxima (**+u**\|\ **U**) for each column. Append **+l**\|\ **L** to look for minima instead. Upper case **+L** means we find the minimum of the positive values only, while upper case **+U** means we find the maximum of the negative values only [use all values]. We only allow one input grid when |-E| is selected. .. _-F: **-F** Report grid domain and x/y-increments in world mapping format [Default is generic]. Does not apply to the |-C| option. .. _-G: **-G** Force (possible) download of all tiles of tiled global remote grids in order to report the requested information [refuse to give the information for tiled grids]. .. _-I: **-I**\ [*dx*\ [/*dy*]\|\ **b**\|\ **i**\|\ **o**\|\ **r**] Report the min/max of the region to the nearest multiple of *dx* and *dy*, and output this in the form |-R|\ *w/e/s/n* (unless |-C| is set). To report the actual grid region, select |-I|\ **r** for the format |-R|\ *w/e/s/n* or |-I|\ **o** for the oblique format |-R|\ *w/s/e/n*\ **+r**. For a grid produced by the img supplement (a Cartesian Mercator grid), the exact geographic region is given with |-I|\ **i** (if not found then we return the actual grid region instead). If no argument is given then we report the grid increment in the form |-I|\ *xinc*\ [/*yinc*]. If |-I|\ **b** is given we write each grid's bounding box polygon instead. Finally, if |-D| is in effect then *dx* and *dy* are the dimensions of the desired tiles. .. _-L: **-L**\ [**0**\|\ **1**\|\ **2**\|\ **p**\|\ **a**] Select various statistical reports of the grid values. Choose from these directives: - **0**: Report range of *v* after actually scanning the data, not just reporting what the header says. - **1**: Report median and L1 scale of *v* (L1 scale = 1.4826 \* Median Absolute Deviation (MAD)). - **2**: Report mean, standard deviation (L2 scale), and root-mean-square (rms) of *v* [Default]. - **p**: Report mode (LMS) and LMS scale of *v*. - **a**: Report all of the above. **Note**: If the grid is geographic then each node represents a physical area that decreases with increasing latitude. We therefore report spherically weighted statistical estimates for such grids. .. _-M: **-M**\ [**c**\|\ **f**] Find and report the location of min/max *v*-values, and count and report the number of nodes set to NaN, if any [Default]. Use directive **f** to instead force an update of the *v*-value min/max by reading the matrix, or use **c** for conditionally doing so if the header information does not contain a valid *v* range. .. |Add_-R| replace:: Using the |-R| option will select a subsection of the input grid(s). If this subsection exceeds the boundaries of the grid, only the common region will be extracted. For cubes you must also append limits in the *z* dimension. |Add_-R_links| .. include:: explain_-R.rst_ :start-after: **Syntax** :end-before: **Description** .. _-T: **-T**\ [*dv*]\ [**+a**\ [*alpha*]]\ [**+s**] Determine min and max data value. If *dv* is provided then we first round these values off to multiples of *dv*. To exclude the two tails of the distribution when determining the min and max you can add **+a** to set the combined *alpha* value (in percent [2]): We then sort the values, exclude the data in the 0.5*\ *alpha* and 100 - 0.5*\ *alpha* tails, and revise the min and max. Give *alpha* in the format *alphaL*/*alphaR* to select unequal tail areas. To force a symmetrical range about zero, using minus/plus the max absolute value of the two extremes, append **+s**. We report the result via the text string |-T|\ *vmin/vmax* or |-T|\ *vmin/vmax/dv* (if *dv* was given) as expected by :doc:`makecpt`. .. |Add_-V| replace:: |Add_-V_links| .. include:: explain_-V.rst_ :start-after: **Syntax** :end-before: **Description** .. |Add_-f| unicode:: 0x20 .. just an invisible code .. include:: explain_-f.rst_ .. |Add_-h| unicode:: 0x20 .. just an invisible code .. include:: explain_-h.rst_ .. include:: explain_-ocols.rst_ .. include:: explain_help.rst_ Examples -------- To obtain all the information about the remote data set in file earth_relief_10m:: gmt grdinfo -L1 -L2 -M @earth_relief_10m Get the grid spacing in earth_relief_10m:: dx=`gmt grdinfo -Cn -o7 @earth_relief_10m` To learn about the extreme values and coordinates in the 3-D data cube S362ANI_kmps.nc?vs:: gmt grdinfo -M S362ANI_kmps.nc?vs **Note**: if you do a subset of a remote tiled file, e.g., earth_relief_01m, you must add |-G| so that any missing tiles are first downloaded:: gmt grdinfo @earth_relief_01m_p -R118/125/20/26 -G -C -M See Also -------- :doc:`gmt`, :doc:`grd2cpt`, :doc:`grd2xyz`, :doc:`grdedit`, :doc:`grdselect`