.. index:: ! grdhisteq
.. include:: module_core_purpose.rst_

*********
grdhisteq
*********

|grdhisteq_purpose|

Synopsis
--------

.. include:: common_SYN_OPTs.rst_

**gmt grdhisteq** *ingrid* [ |-G|\ *outgrid* ]
[ |-C|\ *n_cells* ] [ |-D|\ [*file*] ] [ |-N|\ [*norm*] ]
[ |-Q| ]
[ |SYN_OPT-R| ]
[ |SYN_OPT-V| ]
[ |SYN_OPT-h| ]
[ |SYN_OPT--| ]

|No-spaces|

Description
-----------

**grdhisteq** allows the user to find the data values which divide a
given grid file into patches of equal area. One common use of
**grdhisteq** is in a kind of histogram equalization of an image. In
this application, the user might have a grid of flat topography with a
mountain in the middle. Ordinary gray shading of this file (using
:doc:`grdimage` or :doc:`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. One could use **grdhisteq** to write to standard output or file an
ASCII list of those data values which divide the range of the data into
*n_cells* segments, each of which has an equal area in the image. Using
**awk** or :doc:`makecpt` one can take this output and build a CPT;
using the CPT with :doc:`grdimage` will result in an image with all levels
of gray occurring equally. Alternatively, see :doc:`grd2cpt`.

The second common use of **grdhisteq** is in writing a grid with
statistics based on some kind of cumulative distribution function. In
this application, the output has relative highs and lows in the same
(x,y) locations as the input file, but the values are changed to reflect
their place in some cumulative distribution. One example would be to
find the lowest 10% of the data: Take a grid, run **grdhisteq** and make
a grid using *n_cells* = 10, and then contour the result to trace the 1
contour. This will enclose the lowest 10% of the data, regardless of
their original values. Another example is in equalizing the output of
:doc:`grdgradient`. For shading purposes it is desired that the data have a
smooth distribution, such as a Gaussian. If you run **grdhisteq** on
output from :doc:`grdgradient` and make a grid file output with the
Gaussian option, you will have a grid whose values are distributed
according to a Gaussian distribution with zero mean and unit variance.
The locations of these values will correspond to the locations of the
input; that is, the most negative output value will be in the (x,y)
location of the most negative input value, and so on.

Required Arguments
------------------

.. |Add_ingrid| replace:: 2-D grid file to be equalized.
.. include:: explain_grd_inout.rst_
    :start-after: ingrid-syntax-begins
    :end-before: ingrid-syntax-ends

Optional Arguments
------------------

.. _-C:

**-C**\ *n_cells*
    Sets how many cells (or divisions) of data range to make [16].

.. _-D:

**-D**\ [*file*]
    Dump level information to *file*, or standard output if no file is provided.

.. _-G:

.. |Add_outgrid| replace:: Give the name of the output grid file. Used with |-N| only.
.. include:: /explain_grd_inout.rst_
    :start-after: outgrid-syntax-begins
    :end-before: outgrid-syntax-ends

.. _-N:

**-N**\ [*norm*]
    Gaussian output. Use with |-G| to make an output grid with
    standard normal scores. Append *norm* to force the scores to fall in
    the ±\ *norm* range [Default is standard normal scores].

.. _-Q:

**-Q**
    Quadratic output. Selects quadratic histogram equalization. [Default is linear].

.. |Add_-R| replace:: Using the |-R| option will select a subsection of *ingrid* grid. If this subsection
    exceeds the boundaries of the grid, only the common region will be extracted. |Add_-R_links|
.. include:: explain_-R.rst_
    :start-after: **Syntax**
    :end-before: **Description**

.. |Add_-V| replace:: |Add_-V_links|
.. include:: explain_-V.rst_
    :start-after: **Syntax**
    :end-before: **Description**

.. |Add_-h| unicode:: 0x20 .. just an invisible code
.. include:: explain_-h.rst_

.. include:: explain_help.rst_

Examples
--------

.. include:: explain_example.rst_

To find the height intervals that divide the selected region of the remote file
earth_relief_05m into 16 divisions of equal area::

    gmt grdhisteq -C16 -D @earth_relief_05m -R0/20/0/20 > levels.txt

To make the poorly distributed intensities in the file raw_intens.nc
suitable for use with :doc:`grdimage` or :doc:`grdview`, run

   ::

    gmt grdhisteq raw_intens.nc -Gsmooth_intens.nc -N -V

Notes
------

#. For geographical grids we do a weighted histogram equalization since the
   area of each node varies with latitude.
#. If you use **grdhisteq** to make a Gaussian output for gradient shading
   in :doc:`grdimage` or :doc:`grdview`, you should be aware of the following:
   the output will be in the range [-x, x], where x is based on the number
   of data in the input grid (nx \* ny) and the cumulative Gaussian
   distribution function F(x). That is, let N = nx \* ny. Then x will be
   adjusted so that F(x) = (N - 1 + 0.5)/N. Since about 68% of the values
   from a standard normal distribution fall within ±\ 1, this will be true
   of the output grid. But if N is very large, it is possible for x to be
   greater than 4. Therefore, with the :doc:`grdview` program clipping
   gradients to the range [-1, 1], you will get correct shading of 68% of
   your data, while 16% of them will be clipped to -1 and 16% of them
   clipped to +1. If this makes too much of the image too light or too
   dark, you should take the output of **grdhisteq** and rescale it using
   :doc:`grdmath` and multiplying by something less than 1.0, to shrink the
   range of the values, thus bringing more than 68% of the image into the
   range [-1, 1]. Alternatively, supply a normalization factor with |-N|.

See Also
--------

:doc:`gmt`, :doc:`gmt.conf`,
:doc:`grd2cpt`,
:doc:`grdgradient`,
:doc:`grdimage`, :doc:`grdmath`,
:doc:`grdview`, :doc:`makecpt`
