Add parameters to histogram (#1249)

Co-authored-by: Wei Ji <[email protected]>
Co-authored-by: Dongdong Tian <[email protected]>

Author: 3 people

pygmt/src/histogram.py

@@ -10,16 +10,29 @@
     A="horizontal",
     B="frame",
     C="cmap",
+    D="annotate",
+    E="barwidth",
+    F="center",
     G="fill",
     J="projection",
+    L="extreme",
+    N="distribution",
+    Q="cumulative",
     R="region",
+    S="stairs",
     T="series",
+    U="timestamp",
+    V="verbose",
     W="pen",
+    X="xshift",
+    Y="yshift",
+    Z="type",
     c="panel",
     l="label",
     p="perspective",
+    t="transparency",
 )
-@kwargs_to_strings(R="sequence", T="sequence")
+@kwargs_to_strings(R="sequence", T="sequence", c="sequence_comma", p="sequence")
 def histogram(self, table, **kwargs):
     r"""
     Plots a histogram, and can read data from a file or
@@ -40,16 +53,75 @@ def histogram(self, table, **kwargs):
     {G}
     {W}
     {c}
-    label : str
-        Add a legend entry for the symbol or line being plotted.
-    {p}
+    annotate : bool or str
+        [**+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.
+    barwidth : int or float or str
+        *width*\ [**+o**\ *offset*].
+        Use an alternative histogram bar width than the default set via
+        ``series``, and optionally shift all bars by an *offset*.  Here
+        *width* is either an alternative width in data units, or the user may
+        append a valid plot dimension unit (**c**\|\ **i**\|\ **p**) for a
+        fixed dimension instead. Optionally, all bins may be shifted along the
+        axis by *offset*. As for *width*, it may be given in data units of
+        plot dimension units by appending the relevant unit.
+    center : bool
+        Center bin on each value. [Default is left edge].
+    distribution : bool or int or float or str
+        [*mode*][**+p**\ *pen*].
+        Draw the equivalent normal distribution; append desired
+        *pen* [Default is 0.25p,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.
+    cumulative : bool or str
+        [**r**].
+        Draw a cumulative histogram by passing ``True``. Use **r** to display
+        a reverse cumulative histogram.
+    extreme : str
+        **l**\|\ **h**\|\ **b**.
+        The modifiers specify the handling of extreme values that fall outside
+        the range set by ``series``.  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**.
+    stairs : bool
+        Draws a stairs-step diagram which does not include the internal bars
+        of the default histogram.
     horizontal : bool
         Plot the histogram using horizonal bars instead of the
         default vertical bars.
     series : int or str or list
-        [*min*\ /*max*\ /]\ *inc*\ [**+n**\ ]
+        [*min*\ /*max*\ /]\ *inc*\ [**+n**\ ].
         Set the interval for the width of each bar in the histogram.
+    type : int or str
+        [*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**.
+    {XY}
+    {U}
+    {V}
+    label : str
+        Add a legend entry for the symbol or line being plotted.
+    {p}
+    {t}
     """
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
     with Session() as lib: