diff --git a/doc/api/index.rst b/doc/api/index.rst index 7d30a2a0d75..833516553ae 100644 --- a/doc/api/index.rst +++ b/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 diff --git a/pygmt/figure.py b/pygmt/figure.py index b6b7128c060..b78d6a9f29a 100644 --- a/pygmt/figure.py +++ b/pygmt/figure.py @@ -411,6 +411,7 @@ def _repr_html_(self): grdcontour, grdimage, grdview, + histogram, image, inset, legend, diff --git a/pygmt/src/__init__.py b/pygmt/src/__init__.py index 22821804822..eb87050b362 100644 --- a/pygmt/src/__init__.py +++ b/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 diff --git a/pygmt/src/histogram.py b/pygmt/src/histogram.py new file mode 100644 index 00000000000..3759a27061e --- /dev/null +++ b/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) diff --git a/pygmt/tests/baseline/test_histogram.png.dvc b/pygmt/tests/baseline/test_histogram.png.dvc new file mode 100644 index 00000000000..33b740d0fb4 --- /dev/null +++ b/pygmt/tests/baseline/test_histogram.png.dvc @@ -0,0 +1,4 @@ +outs: +- md5: 8499f1d0ef232ece53300c6aaf611607 + size: 10794 + path: test_histogram.png diff --git a/pygmt/tests/test_histogram.py b/pygmt/tests/test_histogram.py new file mode 100644 index 00000000000..77dd5f03807 --- /dev/null +++ b/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