Add Figure.vlines for plotting vertical lines (#3726)

Author: seisman

doc/api/index.rst

@@ -36,6 +36,7 @@ Plotting map elements
     Figure.solar
     Figure.text
     Figure.timestamp
+    Figure.vlines
 
 Plotting tabular data
 ~~~~~~~~~~~~~~~~~~~~~

pygmt/figure.py

@@ -437,6 +437,7 @@ def _repr_html_(self) -> str:
         tilemap,
         timestamp,
         velo,
+        vlines,
         wiggle,
     )
 

pygmt/src/__init__.py

@@ -57,6 +57,7 @@
 from pygmt.src.timestamp import timestamp
 from pygmt.src.triangulate import triangulate
 from pygmt.src.velo import velo
+from pygmt.src.vlines import vlines
 from pygmt.src.which import which
 from pygmt.src.wiggle import wiggle
 from pygmt.src.x2sys_cross import x2sys_cross

pygmt/src/hlines.py

@@ -48,7 +48,7 @@ def hlines(
         Y-coordinates to plot the lines. It can be a single value (for a single line)
         or a sequence of values (for multiple lines).
     xmin/xmax
-        X-coordinates of the start/end point of the line(s). If ``None``, defaults to
+        X-coordinates of the start/end point(s) of the line(s). If ``None``, defaults to
         the X-limits of the current plot. ``xmin`` and ``xmax`` can be either a single
         value or a sequence of values. If a single value is provided, it is applied to
         all lines. If a sequence is provided, the length of ``xmin`` and ``xmax`` must

pygmt/src/vlines.py

@@ -0,0 +1,132 @@
+"""
+vlines - Plot vertical lines.
+"""
+
+from collections.abc import Sequence
+
+import numpy as np
+from pygmt.exceptions import GMTInvalidInput
+
+__doctest_skip__ = ["vlines"]
+
+
+def vlines(
+    self,
+    x: float | Sequence[float],
+    ymin: float | Sequence[float] | None = None,
+    ymax: float | Sequence[float] | None = None,
+    pen: str | None = None,
+    label: str | None = None,
+    no_clip: bool = False,
+    perspective: str | bool | None = None,
+):
+    """
+    Plot one or multiple vertical line(s).
+
+    This method is a high-level wrapper around :meth:`pygmt.Figure.plot` that focuses on
+    plotting vertical lines at X-coordinates specified by the ``x`` parameter. The ``x``
+    parameter can be a single value (for a single vertical line) or a sequence of values
+    (for multiple vertical lines).
+
+    By default, the Y-coordinates of the start and end points of the lines are set to be
+    the Y-limits of the current plot, but this can be overridden by specifying the
+    ``ymin`` and ``ymax`` parameters. ``ymin`` and ``ymax`` can be either a single value
+    or a sequence of values. If a single value is provided, it is applied to all lines.
+    If a sequence is provided, the length of ``ymin`` and ``ymax`` must match the length
+    of ``x``.
+
+    The term "vertical" lines can be interpreted differently in different coordinate
+    systems:
+
+    - **Cartesian** coordinate system: lines are plotted as straight lines.
+    - **Polar** projection: lines are plotted as straight lines along radius.
+    - **Geographic** projection: lines are plotted as meridians along constant
+      longitude.
+
+    Parameters
+    ----------
+    x
+        X-coordinates to plot the lines. It can be a single value (for a single line)
+        or a sequence of values (for multiple lines).
+    ymin/ymax
+        Y-coordinates of the start/end point(s) of the line(s). If ``None``, defaults to
+        the Y-limits of the current plot. ``ymin`` and ``ymax`` can either be a single
+        value or a sequence of values. If a single value is provided, it is applied to
+        all lines. If a sequence is provided, the length of ``ymin`` and ``ymax`` must
+        match the length of ``x``.
+    pen
+        Pen attributes for the line(s), in the format of *width,color,style*.
+    label
+        Label for the line(s), to be displayed in the legend.
+    no_clip
+        If ``True``, do not clip lines outside the plot region. Only makes sense in the
+        Cartesian coordinate system.
+    perspective
+        Select perspective view and set the azimuth and elevation angle of the
+        viewpoint. Refer to :meth:`pygmt.Figure.plot` for details.
+
+    Examples
+    --------
+    >>> import pygmt
+    >>> fig = pygmt.Figure()
+    >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c/10c", frame=True)
+    >>> fig.vlines(x=1, pen="1p,black", label="Line at x=1")
+    >>> fig.vlines(x=2, ymin=2, ymax=8, pen="1p,red,-", label="Line at x=2")
+    >>> fig.vlines(x=[3, 4], ymin=3, ymax=7, pen="1p,black,.", label="Lines at x=3,4")
+    >>> fig.vlines(x=[5, 6], ymin=4, ymax=9, pen="1p,red", label="Lines at x=5,6")
+    >>> fig.vlines(
+    ...     x=[7, 8], ymin=[0, 1], ymax=[7, 8], pen="1p,blue", label="Lines at x=7,8"
+    ... )
+    >>> fig.legend()
+    >>> fig.show()
+    """
+    self._preprocess()
+
+    # Determine the y limits from the current plot region if not specified.
+    if ymin is None or ymax is None:
+        ylimits = self.region[2:]
+        if ymin is None:
+            ymin = ylimits[0]
+        if ymax is None:
+            ymax = ylimits[1]
+
+    # Ensure x/ymin/ymax are 1-D arrays.
+    _x = np.atleast_1d(x)
+    _ymin = np.atleast_1d(ymin)
+    _ymax = np.atleast_1d(ymax)
+
+    nlines = len(_x)  # Number of lines to plot.
+
+    # Check if ymin/ymax are scalars or have the expected length.
+    if _ymin.size not in {1, nlines} or _ymax.size not in {1, nlines}:
+        msg = (
+            f"'ymin' and 'ymax' are expected to be scalars or have lengths '{nlines}', "
+            f"but lengths '{_ymin.size}' and '{_ymax.size}' are given."
+        )
+        raise GMTInvalidInput(msg)
+
+    # Repeat ymin/ymax to match the length of x if they are scalars.
+    if nlines != 1:
+        if _ymin.size == 1:
+            _ymin = np.repeat(_ymin, nlines)
+        if _ymax.size == 1:
+            _ymax = np.repeat(_ymax, nlines)
+
+    # Call the Figure.plot method to plot the lines.
+    for i in range(nlines):
+        # Special handling for label.
+        # 1. Only specify a label when plotting the first line.
+        # 2. The -l option can accept comma-separated labels for labeling multiple lines
+        #    with auto-coloring enabled. We don't need this feature here, so we need to
+        #    replace comma with \054 if the label contains commas.
+        _label = label.replace(",", "\\054") if label and i == 0 else None
+
+        self.plot(
+            x=[_x[i], _x[i]],
+            y=[_ymin[i], _ymax[i]],
+            pen=pen,
+            label=_label,
+            no_clip=no_clip,
+            perspective=perspective,
+            straight_line="y",
+        )

pygmt/tests/baseline/test_vlines_clip.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 4eb9c7fd7e3a803dcc3cde1409ad7fa7
+  size: 7361
+  hash: md5
+  path: test_vlines_clip.png

pygmt/tests/baseline/test_vlines_geographic_global.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 3fb4a271c670e4cbe647838b6fee5a8c
+  size: 67128
+  hash: md5
+  path: test_vlines_geographic_global.png

pygmt/tests/baseline/test_vlines_multiple_lines.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 499b2d08832247673f208b1c0a282c4c
+  size: 13874
+  hash: md5
+  path: test_vlines_multiple_lines.png

pygmt/tests/baseline/test_vlines_one_line.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 2cd30ad55fc660123c67e6a684a5ea21
+  size: 13589
+  hash: md5
+  path: test_vlines_one_line.png

pygmt/tests/baseline/test_vlines_polar_projection.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 1981df3bd9c57cd975b6e74946496175
+  size: 44621
+  hash: md5
+  path: test_vlines_polar_projection.png