Add Figure.hlines for plotting horizontal lines

doc/api/index.rst

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

examples/gallery/lines/horizontal_lines.py

@@ -0,0 +1,30 @@
+"""
+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"],
+ transparency=50,
+)
+
+fig.legend()
+fig.show()

pygmt/figure.py

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

pygmt/src/__init__.py

@@ -23,6 +23,7 @@
 from pygmt.src.grdtrack import grdtrack
 from pygmt.src.grdview import grdview
 from pygmt.src.histogram import histogram
+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,146 @@
+"""
+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(
+ N="no_clip",
+ V="verbose",
+ W="pen",
+ l="label",
+ p="perspective",
+ t="transparency",
+)
+@kwargs_to_strings(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.
+ 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}
+ {V}
+ 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) # pylint: disable=protected-access
+
+ y = np.atleast_1d(y)
+ list_length = len(y)
+
+ # prepare x values
+ def prep_data(xmin, xmax, list_length):
+
+ if xmin is None and xmax is None:
+ with Session() as lib:
+ # get limits from current map boundings if not given
+ # via xmin, xmax
+ x = np.array([[lib.extract_region()[0]], [lib.extract_region()[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])
+
+ return np.atleast_1d(x)
+
+ def prep_style(kwargs, list_length):
+
+ # prepare labels
+ if "l" in kwargs:
+ # if several lines belong to the same label, first set all to None
+ # then replace first entry by the label given via "l"
+ 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):
+ kwargs["W"] = np.repeat(kwargs["W"], list_length)
+ else: # use as default if no pen is given (neither single nor series)
+ kwargs["W"] = np.repeat("1p,black", list_length)
+
+ return kwargs
+
+ # loop over entries
+ x = prep_data(xmin, xmax, list_length)
+ kwargs = prep_style(kwargs, list_length)
+ kwargs_copy = kwargs.copy()
+
+ for index in range(list_length):
+
+ with Session() as lib:
+ if (
+ data_kind(None, [x[0][index], x[1][index]], [y[index], y[index]])
+ == "vectors"
+ ):
+ file_context = lib.virtualfile_from_vectors(
+ np.atleast_1d([x[0][index], x[1][index]]), [y[index], y[index]]
+ )
+ else:
+ raise GMTInvalidInput("Unrecognized data type.")
+
+ kwargs["l"] = kwargs_copy["l"][index]
+ kwargs["W"] = kwargs_copy["W"][index]
+
+ with file_context as fname:
+ lib.call_module("plot", " ".join([fname, build_arg_string(kwargs)]))

pygmt/tests/test_hlines.py

@@ -0,0 +1,34 @@
+"""
+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.basemap(region=[0, 10, 0, 20], projection="X10c/10c", frame=True)
+ fig_ref.hlines(
+ 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.basemap(region="0/10/0/20", projection="X10c/10c", frame=True)
+ fig_test.hlines(
+ 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