# grdinfo

Extract information from 2-D grids or 3-D cubes

## Synopsis

**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**] ]
[ **-R***region* ]
[ **-T**[*dv*][**+a**[*alpha*]][**+s**] ]
[ **-V**[*level*] ]
[ **-f**flags ]
[ **-h**headers ]
[ **-o**flags ]
[ **--PAR**=*value* ]

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

## 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

*ingrid*[=*ID*|?*varname*][**+b***band*][**+d***divisor*][**+n***invalid*][**+o***offset*][**+s***scale*]

Optionally, append =

IDfor reading a specific file format [Default is =nf] or ?varnamefor a specific netCDF variable [Default is the first 2-D grid found by GMT]. The following modifiers are supported:

+b- Select aband[Default is 0].

+d- Divide data values by the givendivisor[Default is 1].

+n- Replace data values matchinginvalidwith NaN.

+o- Offset data values by the givenoffset[Default is 0].

+s- Scale data values by the givenscale[Default is 1].

Note: Any offset is added after any scaling.

## Optional Arguments

**-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**[*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**[**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**Report grid domain and x/y-increments in world mapping format [Default is generic]. Does not apply to the

**-C**option.

**-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**[*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**[**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**[**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.

**-R***xmin*/*xmax*/*ymin*/*ymax*[**+r**][**+u***unit*]Specify the region of interest. 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. (See full description) (See cookbook information).

**-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 makecpt.

**-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**][**+m***segheader*][**+r***remark*][**+t***title*] (more …)Skip or produce header record(s).

**-o***cols*[**+l**][**+d***divisor*][**+s***scale*|**d**|**k**][**+o***offset*][,*…*][,**t**[*word*]] (more …)Select output columns and transformations (0 is first column,

**t**is trailing text, append*word*to write one word only).

**-^**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 argumentsPrint 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 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
```