pygmt.grdhisteq

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

Perform histogram equalization for a grid.

Allows the user to find the data values which divide a given grid file into patches of equal area. One common use of grdhisteq is in a kind of histogram equalization of an image. In this application, the user might have a grid of flat topography with a mountain in the middle. Ordinary gray shading of this file (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. One could use grdhisteq to write to a pandas.DataFrame or ASCII file with a list of those data values which divide the range of the data into n_cells segments, each of which has an equal area in the image. Using awk or pygmt.makecpt one can take this output and build a CPT; using the CPT with pygmt.Figure.grdimage will result in an image with all levels of gray occurring equally. Alternatively, see pygmt.grd2cpt.

The second common use of grdhisteq is in writing a grid with statistics based on some kind of cumulative distribution function. In this application, the output has relative highs and lows in the same (x,y) locations as the input file, but the values are changed to reflect their place in some cumulative distribution. One example would be to find the lowest 10% of the data: Take a grid, run grdhisteq and make a grid using n_cells = 10, and then contour the result to trace the 1 contour. This will enclose the lowest 10% of the data, regardless of their original values. Another example is in equalizing the output of pygmt.grdgradient. For shading purposes it is desired that the data have a smooth distribution, such as a Gaussian. If you run grdhisteq on output from pygmt.grdgradient and make a grid file output with the Gaussian option, you will have a grid whose values are distributed according to a Gaussian distribution with zero mean and unit variance. The locations of these values will correspond to the locations of the input; that is, the most negative output value will be in the (x,y) location of the most negative input value, and so on.

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

Aliases:

• C = divisions

• 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 None) – The name of the output netCDF file with extension .nc to store the grid in.

• divisions (int) – The number of divisions of data range to make [Default is 16].

• 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 is None (default) - xarray.DataArray if outgrid is True - None if outgrid is a str (grid output is stored in outgrid)