Figure.plot: Add the "symbol" parameter to support plotting data points with varying symbols (#1117)

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Author: core-man

pygmt/src/plot.py

@@ -48,7 +48,9 @@
     w="wrap",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
-def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
+def plot(
+    self, data=None, x=None, y=None, size=None, symbol=None, direction=None, **kwargs
+):
     r"""
     Plot lines, polygons, and symbols in 2-D.
 
@@ -87,6 +89,8 @@ def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
     size : 1-D array
         The size of the data points in units specified using ``style``.
         Only valid if using ``x``/``y``.
+    symbol : 1-D array
+        The symbols of the data points. Only valid if using ``x``/``y``.
     direction : list of two 1-D arrays
         If plotting vectors (using ``style="V"`` or ``style="v"``), then
         should be a list of two 1-D arrays with the vector directions. These
@@ -226,13 +230,19 @@ def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
             if is_nonstr_iter(kwargs.get(flag)):
                 extra_arrays.append(kwargs.get(flag))
                 kwargs[flag] = ""
+        # Symbol must be at the last column
+        if is_nonstr_iter(symbol):
+            if "S" not in kwargs:
+                kwargs["S"] = True
+            extra_arrays.append(symbol)
     else:
         for name, value in [
             ("direction", direction),
             ("fill", kwargs.get("G")),
             ("size", size),
             ("intensity", kwargs.get("I")),
             ("transparency", kwargs.get("t")),
+            ("symbol", symbol),
         ]:
             if is_nonstr_iter(value):
                 raise GMTInvalidInput(f"'{name}' can't be 1-D array if 'data' is used.")

pygmt/tests/baseline/test_plot_symbol.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: bf71e5e72529a85d9ac45aa71321962e
+  size: 3798
+  hash: md5
+  path: test_plot_symbol.png

pygmt/tests/test_plot.py

@@ -93,8 +93,8 @@ def test_plot_fail_no_data(data, region):
 
 def test_plot_fail_1d_array_with_data(data, region):
     """
-    Should raise an exception if array fill, size, intensity and transparency are used
-    with matrix.
+    Should raise an exception if arrays of fill, size, intensity, transparency and
+    symbol are specified when data is given.
     """
     fig = Figure()
     kwargs = {"data": data, "region": region, "projection": "X10c", "frame": "afg"}
@@ -106,6 +106,8 @@ def test_plot_fail_1d_array_with_data(data, region):
         fig.plot(style="c0.2c", fill="red", intensity=data[:, 2], **kwargs)
     with pytest.raises(GMTInvalidInput):
         fig.plot(style="c0.2c", fill="red", transparency=data[:, 2] * 100, **kwargs)
+    with pytest.raises(GMTInvalidInput):
+        fig.plot(style="0.2c", fill="red", symbol=["c"] * data.shape[0], **kwargs)
 
 
 @pytest.mark.mpl_image_compare
@@ -297,6 +299,25 @@ def test_plot_sizes_colors_transparencies():
     return fig
 
 
+@pytest.mark.mpl_image_compare
+def test_plot_symbol():
+    """
+    Plot the data using array-like symbols.
+    """
+    fig = Figure()
+    fig.plot(
+        x=[1, 2, 3, 4],
+        y=[1, 1, 1, 1],
+        region=[0, 5, 0, 5],
+        projection="X4c",
+        fill="blue",
+        size=[0.1, 0.2, 0.3, 0.4],
+        symbol=["c", "t", "i", "s"],
+        frame="af",
+    )
+    return fig
+
+
 @pytest.mark.mpl_image_compare(filename="test_plot_matrix.png")
 @pytest.mark.parametrize("fill", ["#aaaaaa", 170])
 def test_plot_matrix(data, fill):