Add new modules to plot horizontal and vertical lines

As discussed in #670 here's a new module (**hlines**) to plot a single or a set of horizontal lines with only defining the desired y-value(s). For discussion I only add the module for horizontal lines at the moment, however, the adjustments to prepare the same for vertical lines is done very quickly.

pygmt/src/hlines.py

@@ -0,0 +1,155 @@
+"""
+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, fmt_docstring, use_alias, kwargs_to_strings, data_kind
+
+@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, pen=None, label=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) or isinstance(xmin, 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)