pygmt.grdhisteq
- pygmt.grdhisteq(grid, *, divisions=None, outfile=None, outgrid=None, region=None, gaussian=None, quadratic=None, verbose=None, header=None, **kwargs)[source]
Perform histogram equalization for a grid.
Two common use cases of
pygmt.grdhisteq
are to find data values that divide a grid into patches of equal area or to write a grid with statistics based on some kind of cumulative distribution function.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
orpygmt.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
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 ifdivisions
is not set]. Thepandas.DataFrame
or ASCII file output can be used to make a colormap withpygmt.makecpt
and an image withpygmt.Figure.grdimage
that has all levels of gray occuring equally.pygmt.grdhisteq
also provides a way to write a grid with statistics based on a cumulative distribution function. In this application, theoutgrid
has relative highs and lows in the same (x,y) locations as thegrid
, 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
Aliases:
C = divisions
D = outfile
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 bool or None) – The name of the output netCDF file with extension .nc to store the grid in.
outfile (str or None) – The name of the output ASCII file to store the results of the histogram equalization in. Not allowed if
outgrid
is used.divisions (int) – Set the number of divisions of the data range.
region (str or list) – Required if this is the first plot command. xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.
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
andoutfile
are None (default)xarray.DataArray if
outgrid
is TrueNone if
outgrid
is a str (grid output is stored inoutgrid
)None if
outfile
is a str (file output is stored inoutfile
)
See also