Add Figure.hlines for plotting horizontal lines

doc/api/index.rst

@@ -31,6 +31,7 @@ Plotting data and laying out the map:
     Figure.grdview
     Figure.image
     Figure.inset
+    Figure.hlines
     Figure.legend
     Figure.logo
     Figure.meca

examples/gallery/line/horizontal-lines.py

@@ -0,0 +1,29 @@
+"""
+Plot horizontal lines
+---------------------
+
+The :meth:`pygmt.Figure.hlines` method can plot horizontal lines based on 
+a given y value. Optionally, the lower and upper limits of the lines can be
+defined, otherwise the current map boundaries are taken. 
+
+"""
+
+import pygmt
+
+fig = pygmt.Figure()
+fig.basemap(region=[0, 10, 0, 11], projection="X10c/10c", frame=True)
+
+fig.hlines(1, label="line1")
+fig.hlines([2, 3], pen="2p,dodgerblue4", label="line2")
+fig.hlines([4, 5], xmin=2, xmax=8, pen="2p,red3", label="line3")
+fig.hlines([6, 7], xmin=[1, 3], xmax=[8, 7], pen="3p,seagreen", label="line4")
+fig.hlines(
+    [8, 9, 10],
+    xmin=[1.3, 3, 2],
+    xmax=[6.5, 7, 5],
+    pen=["4p,darkmagenta", "2p,gold,--", "3.5p,blue,."],
+    label=["line5", "line6", "line7"],
+)
+
+fig.legend()
+fig.show()

pygmt/figure.py

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

pygmt/src/__init__.py

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

pygmt/src/hlines.py

@@ -0,0 +1,164 @@
+"""
+hlines - Plot horizontal lines.
+"""
+import numpy as np
+from pygmt.clib import Session
+from pygmt.exceptions import GMTInvalidInput
+from pygmt.helpers import (
+    build_arg_string,
+    data_kind,
+    fmt_docstring,
+    kwargs_to_strings,
+    use_alias,
+)
+
+
+@fmt_docstring
+@use_alias(
+    B="frame",
+    C="cmap",
+    D="offset",
+    J="projection",
+    N="no_clip",
+    R="region",
+    U="timestamp",
+    V="verbose",
+    W="pen",
+    X="xshift",
+    Y="yshift",
+    Z="zvalue",
+    l="label",
+    p="perspective",
+    t="transparency",
+)
+@kwargs_to_strings(R="sequence", p="sequence")
+def hlines(self, y=None, xmin=None, xmax=None, **kwargs):
+    """
+    Plot one or a collection of horizontal lines.
+
+    Takes a single y value or a list of individual y values and optionally
+    lower and upper x value limits as input.
+
+    Must provide *y*.
+
+    If y values are given without x limits then the current map boundaries are
+    used as lower and upper limits. If only a single set of x limits is given
+    then all lines will have the same length, otherwise give x limits for each
+    individual line. If only a single label is given then all lines are grouped
+    under this label in the legend (if shown). If each line should appear as a
+    single entry in the legend, give corresponding labels for all lines
+    (same for **pen**).
+
+    Parameters
+    ----------
+    y : float or 1d array
+        The y coordinates or an array of y coordinates of the
+        horizontal lines to plot.
+    {J}
+    {R}
+    {B}
+    {CPT}
+    offset : str
+        ``dx/dy``.
+        Offset the line locations by the given amounts
+        *dx/dy* [Default is no offset]. If *dy* is not given it is set
+        equal to *dx*.
+    no_clip : bool or str
+        ``'[c|r]'``.
+        Do NOT clip lines that fall outside map border [Default plots
+        lines whose coordinates are strictly inside the map border only].
+        The option does not apply to lines which are always
+        clipped to the map region. For periodic (360-longitude) maps we
+        must plot all lines twice in case they are clipped by the
+        repeating boundary. ``no_clip=True`` will turn off clipping and not
+        plot repeating lines. Use ``no_clip="r"`` to turn off clipping
+        but retain the plotting of such repeating lines, or use
+        ``no_clip="c"`` to retain clipping but turn off plotting of
+        repeating lines.
+    {W}
+    {U}
+    {V}
+    {XY}
+    zvalue : str or float
+        ``value``.
+        Instead of specifying a line color via **pen**, give it a *value*
+        via **zvalue** and a color lookup table via **cmap**. Requires
+        appending **+z** to **pen** (e.g. ``pen = "5p,+z"``,
+        ``zvalue = 0.8``, ``cmap = "viridis"``).
+    label : str
+        Add a legend entry for the line being plotted.
+    {p}
+    {t}
+        *transparency* can also be a 1d array to set varying transparency
+        for lines.
+    """
+
+    kwargs = self._preprocess(**kwargs)
+
+    list_length = len(np.atleast_1d(y))
+
+    # prepare x vals
+    if xmin is None and xmax is None:
+        # get limits from current map boundings if not given via xmin, xmax
+        with Session() as lib:
+            mapbnds = lib.extract_region()
+            x = np.array([[mapbnds[0]], [mapbnds[1]]])
+            x = np.repeat(x, list_length, axis=1)
+    elif xmin is None or xmax is None:
+        raise GMTInvalidInput(
+            "Must provide both, xmin and xmax if limits are not set automatically."
+        )
+
+    else:
+        # if only a single xmin and xmax without [], repeat to fit size of y
+        if isinstance(xmin, (int, float)):
+            x = np.array([[xmin], [xmax]])
+            x = np.repeat(x, list_length, axis=1)
+        else:
+            if len(xmin) != len(xmax):
+                GMTInvalidInput("Must provide same length for xmin and xmax.")
+            else:
+                x = np.array([xmin, xmax])
+
+    # prepare labels
+    if "l" in kwargs:
+        # if several lines belong to the same label, first take the label,
+        # then set all to None and reset the first entry to the given label
+        if not isinstance(kwargs["l"], list):
+            label2use = kwargs["l"]
+            kwargs["l"] = np.repeat(None, list_length)
+            kwargs["l"][0] = label2use
+    else:
+        kwargs["l"] = np.repeat(None, list_length)
+
+    # prepare pens
+    if "W" in kwargs:
+        # select pen, no series
+        if not isinstance(kwargs["W"], list):
+            pen2use = kwargs["W"]
+            kwargs["W"] = np.repeat(pen2use, list_length)
+    else:  # use as default if no pen is given (neither single nor series)
+        kwargs["W"] = np.repeat("1p,black", list_length)
+
+    # loop over entries
+    kwargs_copy = kwargs.copy()
+
+    for index in range(list_length):
+        y2plt = [np.atleast_1d(y)[index], np.atleast_1d(y)[index]]
+        x2plt = [np.atleast_1d(x)[0][index], np.atleast_1d(x)[1][index]]
+        kind = data_kind(None, x2plt, y2plt)
+
+        with Session() as lib:
+            if kind == "vectors":
+                file_context = lib.virtualfile_from_vectors(
+                    np.atleast_1d(x2plt), np.atleast_1d(y2plt)
+                )
+            else:
+                raise GMTInvalidInput("Unrecognized data type.")
+
+            kwargs["l"] = kwargs_copy["l"][index]
+            kwargs["W"] = kwargs_copy["W"][index]
+
+            with file_context as fname:
+                arg_str = " ".join([fname, build_arg_string(kwargs)])
+                lib.call_module("plot", arg_str)

pygmt/tests/test_hlines.py

@@ -0,0 +1,73 @@
+"""
+Tests for hline.
+"""
+from pygmt import Figure
+from pygmt.helpers.testing import check_figures_equal
+
+
+@check_figures_equal()
+def test_hlines_value_sets():
+    """
+    Passing sets of y, xmin and xmax.
+    """
+
+    fig_ref, fig_test = Figure(), Figure()
+
+    fig_ref.hlines(
+        region=[0, 10, 0, 20],
+        projection="X10c/10c",
+        frame=True,
+        y=[5.5, 10, 6, 11],
+        xmin=[3.1, 6, 0, 1],
+        xmax=[5.5, 7.8, 10, 9],
+        label="test2",
+        pen="4p,green",
+    )
+
+    fig_test.hlines(
+        region="0/10/0/20",
+        projection="X10c/10c",
+        frame=True,
+        y=[5.5, 10, 6, 11],
+        xmin=[3.1, 6, 0, 1],
+        xmax=[5.5, 7.8, 10, 9],
+        label="test2",
+        pen="4p,green",
+    )
+
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_hlines_zvalue():
+    """
+    Passing in color via zvalue.
+    """
+
+    fig_ref, fig_test = Figure(), Figure()
+
+    fig_ref.hlines(
+        region=[0, 10, 0, 20],
+        projection="X10c/10c",
+        frame=True,
+        y=[9.9],
+        xmin=2,
+        xmax=6,
+        pen="5p,+z",
+        zvalue="0.5",
+        cmap="magma",
+    )
+
+    fig_test.hlines(
+        region="0/10/0/20",
+        projection="X10c/10c",
+        frame=True,
+        y=[9.9],
+        xmin=2,
+        xmax=6,
+        pen="5p,+z",
+        zvalue="0.5",
+        cmap="magma",
+    )
+
+    return fig_ref, fig_test