Source code for pygmt.src.grdinfo

"""
grdinfo - Retrieve info about grid file.
"""
from pygmt.clib import Session
from pygmt.helpers import (
    GMTTempFile,
    build_arg_string,
    fmt_docstring,
    kwargs_to_strings,
    use_alias,
)


[docs]@fmt_docstring @use_alias( C="per_column", D="tiles", F="geographic", I="spacing", L="force_scan", M="minmax_pos", R="region", T="nearest_multiple", V="verbose", f="coltypes", ) @kwargs_to_strings(D="sequence", I="sequence", R="sequence") def grdinfo(grid, **kwargs): r""" Get information about a grid. Can read the grid from a file or given as an xarray.DataArray grid. Full option list at :gmt-docs:`grdinfo.html` {aliases} Parameters ---------- grid : str or xarray.DataArray The file name of the input grid or the grid loaded as a DataArray. This is the only required parameter. {region} per_column : str or bool **n**\|\ **t**. Format the report using tab-separated fields on a single line. The output is name *w e s n z0 z1 dx dy nx ny* [ *x0 y0 x1 y1* ] [ *med scale* ] [ *mean std rms* ] [ *n_nan* ] *registration gtype*. The data in brackets are outputted depending on the ``force_scan`` and ``minmax_pos`` parameters. Use **t** to place file name at the end of the output record or, **n** or ``True`` to only output numerical columns. The registration is either 0 (gridline) or 1 (pixel), while gtype is either 0 (Cartesian) or 1 (geographic). The default value is ``False``. This cannot be called if ``geographic`` is also set. tiles : str or list *xoff*\ [/*yoff*][**+i**]. Divide a single grid's domain (or the ``region`` domain, if no grid given) into tiles of size dx times dy (set via ``spacing``). 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 ``per_column`` to instead report four columns with xmin xmax ymin ymax per tile, or use ``per_column="t"`` to also have the region string appended as trailing text. geographic : bool Report grid domain and x/y-increments in world mapping format The default value is ``False``. This cannot be called if ``per_column`` is also set. spacing : str or list *dx*\ [/*dy*]\|\ **b**\|\ **i**\|\ **r**. Report the min/max of the region to the nearest multiple of dx and dy, and output this in the form w/e/s/n (unless ``per_column`` is set). To report the actual grid region, append **r**. For a grid produced by the img supplement (a Cartesian Mercator grid), the exact geographic region is given with **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 *xinc*\ [/*yinc*]. If **b** is given we write each grid's bounding box polygon instead. Finally, if ``tiles`` is in effect then *dx* and *dy* are the dimensions of the desired tiles. force_scan : int or str **0**\|\ **1**\|\ **2**\|\ **p**\|\ **a**. - **0**: Report range of z after actually scanning the data, not just reporting what the header says. - **1**: Report median and L1 scale of z (L1 scale = 1.4826 * Median Absolute Deviation (MAD)). - **2**: Report mean, standard deviation, and root-mean-square (rms) of z. - **p**: Report mode (LMS) and LMS scale of z. - **a**: Include all of the above. minmax_pos : bool Include the x/y values at the location of the minimum and maximum z-values. nearest_multiple : str [*dz*]\ [**+a**\ [*alpha*]]\ [**+s**]. Determine minimum and maximum z-values. If *dz* is provided then we first round these values off to multiples of *dz*. To exclude the two tails of the distribution when determining the minimum and maximum you can add **+a** to set the *alpha* value (in percent): We then sort the grid, exclude the data in the 0.5*\ *alpha* and 100 - 0.5*\ *alpha* tails, and revise the minimum and maximum. To force a symmetrical range about zero, using minus/plus the maximum absolute value of the two extremes, append **+s**. We report the result via the text string *zmin/zmax* or *zmin/zmax/dz* (if *dz* was given) as expected by :func:`pygmt.makecpt`. {verbose} {coltypes} Returns ------- info : str A string with information about the grid. """ with GMTTempFile() as outfile: with Session() as lib: file_context = lib.virtualfile_from_data(check_kind="raster", data=grid) with file_context as infile: lib.call_module( module="grdinfo", args=build_arg_string(kwargs, infile=infile, outfile=outfile.name), ) result = outfile.read() return result