gmt-fork/doc/rst/source/histogram_common.rst_

|No-spaces|

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

Reads *file* [or standard input] and examines the first
data column (or one set by **-i**) to calculate histogram parameters based on
the bin-width provided. Using these parameters, scaling, and optional
range parameters it will plot the histogram. A cumulative histogram may also be specified.

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

.. _-J:

**-Jx**
    *xscale*\ [/*yscale*] (Linear scale(s) in distance unit/data unit), or
    **-JX** with *width*\ [/*height*] dimensions.

.. _-T:

**-T**\ [*min/max*\ /]\ *inc*\ [**+n**] \|\ **-T**\ *file*\|\ *list*
    Make evenly spaced array of bin boundaries from *min* to *max* by *inc*.
    If *min/max* are not given then we default to the range in **-R**.
    For details on array creation, see `Generate 1D Array`_.

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

.. |Add_intables| unicode:: 0x20 .. just an invisible code
.. include:: explain_intables.rst_

.. _-A:

**-A**
    Plot the histogram horizontally from x = 0 [Default is vertically
    from y = 0].  The plot dimensions remain the same, but the two
    axes are flipped.

.. _-B:

.. include:: explain_-B.rst_

.. _-C:

**-C**\ *cpt*
    Give a CPT. The mid x-value for each bar is used to
    look-up the bar color.  If modern mode and no argument is given
    then we select the current CPT.

.. _-D:

**-D**\ [**+b**][**+f**\ *font*][**+o**\ *off*][**+r**]
    Annotate each bar with the count it represents.  Append any of the
    following modifiers: Use **+b** to place the labels beneath the bars
    instead of above; use **+f** to change to another font than the default
    annotation font; use **+o** to change the offset between bar and label [6p];
    use **+r** to rotate the labels from horizontal to vertical.

.. _-F:

**-F**
    Center bin on each value. [Default is left edge].

.. _-G:

**-G**\ *fill* :ref:`(more ...) <-Gfill_attrib>`
    Select filling of bars [Default is no fill].

.. _-I:

**-I**\ [**o**\|\ **O**]
    Inquire about min/max x and y after binning. The *xmin xmax ymin
    ymax* is output; no plotting is done. Append **o** to output an
    ASCII table of the resulting x,y data instead. Upper case **O** will
    output all x,y bin data even when y == 0.

.. _-L:

**-Ll**\|\ **h**\|\ **b**
    The modifiers specify the handling of extreme values that fall outside the range
    set by **-T**.  By default these values are ignored.  Append **b** to let
    these values be included in the first or last bins.  To only include
    extreme values below first bin into the first bin, use **l**, and to
    only include extreme values above the last bin into that last bin, use
    **h**.

.. _-N:

**-N**\ [*mode*][**+p**\ *pen*]
    Draw the equivalent normal distribution; append desired pen [0.5p,black].
    The *mode* selects which central location and scale to use:

    * 0 = mean and standard deviation [Default];
    * 1 = median and L1 scale (1.4826 \* median absolute deviation; MAD);
    * 2 = LMS (least median of squares) mode and scale.

    The **-N** option may be repeated to draw several of these curves.

.. _-Q:

**-Q**\ **r**
    Draw a cumulative histogram. Append **r** to instead compute the
    reverse cumulative histogram.

.. _-R:

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

.. |Add_-Rz| replace:: If not given, we will automatically find reasonable values for the region.
.. include:: explain_-Rz.rst_

.. _-S:

**-S**
    Draws a stairs-step diagram which does not include the internal bars
    of the default histogram.

.. _-U:

.. include:: explain_-U.rst_

.. _-V:

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

.. _-W:

**-W**\ *pen*
    Draw bar outline (or stair-case curve) using the specified pen thickness. [Default is no outline].

.. _-X:

.. include:: explain_-XY.rst_

.. _-Z:

**-Z**\ [*type*][**+w**]
    Choose between 6 types of histograms:

    * 0 = counts [Default]
    * 1 = frequency_percent
    * 2 = log (1.0 + count)
    * 3 = log (1.0 + frequency_percent)
    * 4 = log10 (1.0 + count)
    * 5 = log10 (1.0 + frequency_percent).

    To use weights provided as a second data column instead of pure counts,
    append **+w**.

.. |Add_-bi| replace:: [Default is 2 input columns].
.. include:: explain_-bi.rst_

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

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

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

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

.. include:: explain_-icols.rst_

.. |Add_perspective| unicode:: 0x20 .. just an invisible code
.. include:: explain_perspective.rst_

.. include:: explain_-qi.rst_

.. include:: explain_-t.rst_

.. include:: explain_help.rst_

.. include:: explain_array.rst_