Wrap histogram (#1072)

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

doc/api/index.rst

@@ -29,6 +29,7 @@ Plotting data and laying out the map:
     Figure.grdcontour
     Figure.grdimage
     Figure.grdview
+    Figure.histogram
     Figure.image
     Figure.inset
     Figure.legend

pygmt/figure.py

@@ -411,6 +411,7 @@ def _repr_html_(self):
         grdcontour,
         grdimage,
         grdview,
+        histogram,
         image,
         inset,
         legend,

pygmt/src/__init__.py

@@ -17,6 +17,7 @@
 from pygmt.src.grdinfo import grdinfo
 from pygmt.src.grdtrack import grdtrack
 from pygmt.src.grdview import grdview
+from pygmt.src.histogram import histogram
 from pygmt.src.image import image
 from pygmt.src.info import info
 from pygmt.src.inset import inset

pygmt/src/histogram.py

@@ -0,0 +1,59 @@
+"""
+Histogram - Create a histogram
+"""
+from pygmt.clib import Session
+from pygmt.helpers import build_arg_string, fmt_docstring, kwargs_to_strings, use_alias
+
+
+@fmt_docstring
+@use_alias(
+    A="horizontal",
+    B="frame",
+    C="cmap",
+    G="fill",
+    J="projection",
+    R="region",
+    T="series",
+    W="pen",
+    c="panel",
+    l="label",
+    p="perspective",
+)
+@kwargs_to_strings(R="sequence", T="sequence")
+def histogram(self, table, **kwargs):
+    r"""
+    Plots a histogram, and can read data from a file or
+    list, array, or dataframe.
+
+    Full option list at :gmt-docs:`histogram.html`
+
+    {aliases}
+
+    Parameters
+    ----------
+    table : str, list, or 1d array
+        A data file name, list, or 1d numpy array. This is a required argument.
+    {J}
+    {R}
+    {B}
+    {CPT}
+    {G}
+    {W}
+    {c}
+    label : str
+        Add a legend entry for the symbol or line being plotted.
+    {p}
+    horizontal : bool
+        Plot the histogram using horizonal bars instead of the
+        default vertical bars.
+    series : int or str or list
+        [*min*\ /*max*\ /]\ *inc*\ [**+n**\ ]
+        Set the interval for the width of each bar in the histogram.
+
+    """
+    kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
+    with Session() as lib:
+        file_context = lib.virtualfile_from_data(check_kind="vector", data=table)
+        with file_context as infile:
+            arg_str = " ".join([infile, build_arg_string(kwargs)])
+            lib.call_module("histogram", arg_str)

pygmt/tests/baseline/test_histogram.png.dvc

@@ -0,0 +1,4 @@
+outs:
+- md5: 8499f1d0ef232ece53300c6aaf611607
+  size: 10794
+  path: test_histogram.png

pygmt/tests/test_histogram.py

@@ -0,0 +1,31 @@
+# pylint: disable=redefined-outer-name
+"""
+Tests histogram.
+"""
+import pytest
+from pygmt import Figure
+
+
+@pytest.fixture(scope="module")
+def table():
+    """
+    Returns a list of integers to be used in the histogram.
+    """
+    return [1, 1, 1, 1, 1, 1, 2, 2, 2, 3, 4, 5, 6, 7, 8, 8, 8, 8, 8, 8]
+
+
+@pytest.mark.mpl_image_compare
+def test_histogram(table):
+    """
+    Tests plotting a histogram using a list of integers.
+    """
+    fig = Figure()
+    fig.histogram(
+        table=table,
+        projection="X10c/10c",
+        region=[0, 9, 0, 6],
+        series=1,
+        frame="a",
+        fill="green",
+    )
+    return fig