pygmt.grdhisteq

pygmt.grdhisteq(grid, *, divisions=None, outfile=None, outgrid=None, region=None, gaussian=None, quadratic=None, verbose=None, header=None, **kwargs)[source]

Perform histogram equalization for a grid.

Two common use cases of pygmt.grdhisteq are to find data values that divide a grid into patches of equal area or to write a grid with statistics based on some kind of cumulative distribution function.

Histogram equalization provides a way to highlight data that has most values clustered in a small portion of the dynamic range, such as a grid of flat topography with a mountain in the middle. Ordinary gray shading of this grid (using pygmt.Figure.grdimage or pygmt.Figure.grdview) with a linear mapping from topography to graytone will result in most of the image being very dark gray, with the mountain being almost white. pygmt.grdhisteq can provide a list of data values that divide the data range into divisions which have an equal area in the image [Default is 16 if divisions is not set]. The pandas.DataFrame or ASCII file output can be used to make a colormap with pygmt.makecpt and an image with pygmt.Figure.grdimage that has all levels of gray occuring equally.

pygmt.grdhisteq also provides a way to write a grid with statistics based on a cumulative distribution function. In this application, the outgrid has relative highs and lows in the same (x,y) locations as the grid, but the values are changed to reflect their place in the cumulative distribution.

Full option list at https://docs.generic-mapping-tools.org/latest/grdhisteq.html

Aliases:

  • C = divisions

  • D = outfile

  • G = outgrid

  • N = gaussian

  • Q = quadratic

  • R = region

  • V = verbose

  • h = header

Parameters
  • grid (str or xarray.DataArray) – The file name of the input grid or the grid loaded as a DataArray.

  • outgrid (str or bool or None) – The name of the output netCDF file with extension .nc to store the grid in.

  • outfile (str or None) – The name of the output ASCII file to store the results of the histogram equalization in. Not allowed if outgrid is used.

  • divisions (int) – Set the number of divisions of the data range.

  • region (str or list) – Required if this is the first plot command. xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

  • verbose (bool or str) –

    Select verbosity level [Default is w], which modulates the messages written to stderr. Choose among 7 levels of verbosity:

    • q - Quiet, not even fatal error messages are produced

    • e - Error messages only

    • w - Warnings [Default]

    • t - Timings (report runtimes for time-intensive algorithms);

    • i - Informational messages (same as verbose=True)

    • c - Compatibility warnings

    • d - Debugging messages

  • header (str) –

    [i|o][n][+c][+d][+msegheader][+rremark][+ttitle]. Specify that input and/or output file(s) have n header records [Default is 0]. Prepend i if only the primary input should have header records. Prepend o to control the writing of header records, with the following modifiers supported:

    • +d to remove existing header records.

    • +c to add a header comment with column names to the output [Default is no column names].

    • +m to add a segment header segheader to the output after the header block [Default is no segment header].

    • +r to add a remark comment to the output [Default is no comment]. The remark string may contain \n to indicate line-breaks.

    • +t to add a title comment to the output [Default is no title]. The title string may contain \n to indicate line-breaks.

    Blank lines and lines starting with # are always skipped.

Returns

ret (pandas.DataFrame or xarray.DataArray or None) – Return type depends on whether the outgrid parameter is set:

  • pandas.DataFrame if outgrid and outfile are None (default)

  • xarray.DataArray if outgrid is True

  • None if outgrid is a str (grid output is stored in outgrid)

  • None if outfile is a str (file output is stored in outfile)

See also

pygmt.grd2cpt