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

pygmt/src/plot.py

@@ -43,7 +43,9 @@
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
-def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
+def plot(
+    self, x=None, y=None, data=None, sizes=None, direction=None, symbol=None, **kwargs
+):
     r"""
     Plot lines, polygons, and symbols in 2-D.
 
@@ -86,6 +88,8 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         should be a list of two 1d arrays with the vector directions. These
         can be angle and length, azimuth and length, or x and y components,
         depending on the style options chosen.
+    symbol : 1d array
+        The symbols of the data points. Only valid if using ``x``/``y``.
     {J}
     {R}
     straight_line : bool or str
@@ -206,15 +210,18 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
     kind = data_kind(data, x, y)
 
     extra_arrays = []
-    if "S" in kwargs and kwargs["S"][0] in "vV" and direction is not None:
-        extra_arrays.extend(direction)
+    if "S" in kwargs and isinstance(kwargs["S"], str):
+        if kwargs["S"][0] in "vV" and direction is not None:
+            extra_arrays.extend(direction)
+
     if "G" in kwargs and not isinstance(kwargs["G"], str):
         if kind != "vectors":
             raise GMTInvalidInput(
                 "Can't use arrays for color if data is matrix or file."
             )
         extra_arrays.append(kwargs["G"])
         del kwargs["G"]
+
     if sizes is not None:
         if kind != "vectors":
             raise GMTInvalidInput(
@@ -231,6 +238,16 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
             extra_arrays.append(kwargs[flag])
             kwargs[flag] = ""
 
+    if symbol is not None:
+        if "S" not in kwargs:
+            kwargs["S"] = True
+
+        if kind != "vectors":
+            raise GMTInvalidInput(
+                "Can't use arrays for symbol if data is matrix or file."
+            )
+        extra_arrays.append(symbol)
+
     with Session() as lib:
         # Choose how data will be passed in to the module
         file_context = lib.virtualfile_from_data(

pygmt/tests/baseline/test_plot_symbols.png.dvc

@@ -0,0 +1,4 @@
+outs:
+- md5: 394a4e806a99234f239437252a99254c
+  size: 13759
+  path: test_plot_symbols.png

pygmt/tests/test_plot.py

@@ -91,19 +91,23 @@ def test_plot_fail_no_data(data):
         )
 
 
-def test_plot_fail_color_size_intensity(data):
+def test_plot_fail_1d_array_using_data(data):
     """
-    Should raise an exception if array color, sizes and intensity are used with
-    matrix.
+    Should raise an exception if array color, sizes, intensity and symbol are
+    used with matrix.
     """
     fig = Figure()
     kwargs = dict(data=data, region=region, projection="X10c", frame="afg")
     with pytest.raises(GMTInvalidInput):
         fig.plot(style="c0.2c", color=data[:, 2], **kwargs)
     with pytest.raises(GMTInvalidInput):
-        fig.plot(style="cc", sizes=data[:, 2], color="red", **kwargs)
+        fig.plot(style="cc", color="red", sizes=data[:, 2], **kwargs)
     with pytest.raises(GMTInvalidInput):
         fig.plot(style="c0.2c", color="red", intensity=data[:, 2], **kwargs)
+    with pytest.raises(GMTInvalidInput):
+        fig.plot(
+            style="0.2c", color="red", symbol=np.full(len(data[:, 2]), "c"), **kwargs
+        )
 
 
 @pytest.mark.mpl_image_compare
@@ -295,6 +299,25 @@ def test_plot_sizes_colors_transparencies():
     return fig
 
 
+@pytest.mark.mpl_image_compare
+def test_plot_symbols(data, region):
+    """
+    Plot the data using array-like symbols.
+    """
+    fig = Figure()
+    fig.plot(
+        x=data[:, 0],
+        y=data[:, 1],
+        region=region,
+        projection="X4c",
+        color="blue",
+        sizes=np.full(len(data[:, 0]), 0.5),
+        symbol=np.full(len(data[:, 0]), "c"),
+        frame="af",
+    )
+    return fig
+
+
 @pytest.mark.mpl_image_compare
 def test_plot_matrix(data):
     """