pygmt.grdhisteq.compute_bins

static grdhisteq.compute_bins(grid, *, output_type='pandas', outfile=None, divisions=None, quadratic=None, verbose=None, region=None)[source]

Perform histogram equalization for a grid.

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.compute_bins 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.

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.
outfile (str or bool or None) – The name of the output ASCII file to store the results of the histogram equalization in.
output_type (str) –
Determine the format the xyz data will be returned in [Default is pandas]:
- numpy - numpy.ndarray
- pandas- pandas.DataFrame
- file - ASCII file (requires outfile)
divisions (int) – Set the number of divisions of the data 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 (pandas.DataFrame or None) – Return type depends on the outfile parameter:

pandas.DataFrame if outfile is True or None
None if outfile is a str (file output is stored in outfile)

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]
... )
>>> # Find elevation intervals that splits the data range into 5
>>> # divisions, each of which have an equal area in the original grid.
>>> bins = pygmt.grdhisteq.compute_bins(grid=grid, divisions=5)
>>> print(bins)
        start    stop
bin_id
0       179.0   397.5
1       397.5   475.5
2       475.5   573.5
3       573.5   710.5
4       710.5  2103.0