pygmt.grdhisteq.equalize_grid

static grdhisteq.equalize_grid(grid, *, outgrid=None, divisions=None, region=None, gaussian=None, quadratic=None, verbose=None)[source]

Perform histogram equalization for a grid.

pygmt.grdhisteq.equalize_grid provides a way to write a grid with statistics based on a cumulative distribution function. 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

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) – Set the number of divisions of the data range.
gaussian (bool or int or float) – norm. Produce an output grid with standard normal scores using gaussian=True or force the scores to fall in the ±norm range.
quadratic (bool) – Perform quadratic equalization [Default is linear].
region (str or list) – 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

Returns

ret (xarray.DataArray or None) – Return type depends on the outgrid parameter:

xarray.DataArray if outgrid is None
None if outgrid is a str (grid output is stored in outgrid)

Example

>>> import pygmt
>>> # Load a grid of @earth_relief_30m data, with an x-range of 10 to
>>> # 30, and a y-range of 15 to 25
>>> grid = pygmt.datasets.load_earth_relief(
...     resolution="30m", region=[10, 30, 15, 25]
... )
>>> # Create a new grid with a Gaussian data distribution
>>> grid = pygmt.grdhisteq.equalize_grid(grid=grid, gaussian=True)