pygmt.grdhisteq.compute_bins

static grdhisteq.compute_bins(grid, output_type='pandas', outfile=None, **kwargs)[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 occurring equally.

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

Aliases:

  • C = divisions

  • N = gaussian

  • Q = quadratic

  • R = region

  • V = verbose

  • h = header

Parameters:

  • 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 https://docs.generic-mapping-tools.org/6.5/gmt.html#grd-inout-full for the available modifiers.

  • output_type (Literal['pandas', 'numpy', 'file'], default: 'pandas') –

    Desired output type of the result data.

    • pandas will return a pandas.DataFrame object.

    • numpy will return a numpy.ndarray object.

    • file will save the result to the file specified by the outfile parameter.

  • outfile (str | None, default: None) – File name for saving the result data. Required if output_type="file". If specified, output_type will be forced to be "file".

  • 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

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

Return type:

DataFrame | ndarray | None

Returns:

ret – Return type depends on outfile and output_type:

  • None if outfile is set (output will be stored in file set by outfile)

  • pandas.DataFrame or numpy.ndarray if outfile is not set (depends on output_type)

Example

>>> 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]
... )
>>> # Find elevation intervals that split 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       183.5   395.0
1       395.0   472.0
2       472.0   575.0
3       575.0   709.5
4       709.5  1807.0

See also

pygmt.grd2cpt

Note

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

Examples using pygmt.grdhisteq.compute_bins

Performing grid histogram equalization

Performing grid histogram equalization