added further content

Author: michaelgrund

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

@@ -4,42 +4,50 @@
 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
+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",
-    )
+    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 
+    """
+    " Plot one or a collection of horizontal lines.
 
-    Takes a single y value or a list of individual y values and optionally 
+    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**). 
+    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
     ----------
@@ -73,83 +81,84 @@ def hlines(self, y=None, xmin=None, xmax=None, pen=None, label=None, **kwargs):
     {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"``).
+        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: 
+    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)         
+        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:   
+        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)    
+        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         
+                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   
+            kwargs["l"][0] = label2use
     else:
-        kwargs["l"] = np.repeat(None, list_length)   
-        
-      
-    # prepare pens    
+        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(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  
+    # 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)
+        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)