added further content

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)