static grdhisteq.equalize_grid(grid, outgrid=None, **kwargs)[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


  • C = divisions

  • N = gaussian

  • Q = quadratic

  • R = region

  • V = verbose

  • h = header

  • grid (str or xarray.DataArray) –

    Name of the input grid file or the grid loaded as a xarray.DataArray object.

    For reading a specific grid file format or applying basic data operations, see for the available modifiers.

  • outgrid (str | None, default: None) – Name of the output netCDF grid file. If not specified, will return an xarray.DataArray object. For writing a specific grid file format or applying basic data operations to the output grid, see for the available modifiers.

  • 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


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)


>>> import pygmt
>>> # Load a grid of @earth_relief_30m data, with a longitude range
>>> # of 10°E to 30°E, and a latitude range of 15°N to 25°N
>>> 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)

See also



This method does a weighted histogram equalization for geographic grids to account for node area varying with latitude.

Examples using pygmt.grdhisteq.equalize_grid

Performing grid histogram equalization

Performing grid histogram equalization