Allow passing a array as intensity for plot (GenericMappingTools#1065)

Co-authored-by: Dongdong Tian <[email protected]>
Co-authored-by: Wei Ji <[email protected]>

pygmt/src/plot.py

@@ -144,11 +144,13 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         the coordinates of a *refpoint* which will serve as a fixed external
         reference point for all groups.
     {G}
-    intensity : float or bool
-        Provide an *intens* value (nominally in the -1 to +1 range) to
-        modulate the fill color by simulating illumination [None]. If
-        using ``intensity=True``, we will instead read *intens* from the
-        first data column after the symbol parameters (if given).
+    intensity : float or bool or 1d array
+        Provide an *intensity* value (nominally in the -1 to +1 range) to
+        modulate the fill color by simulating illumination. If using
+        ``intensity=True``, we will instead read *intensity* from the first
+        data column after the symbol parameters (if given). *intensity* can
+        also be a 1d array to set varying intensity for symbols, but it is only
+        valid for ``x``/``y`` pairs.
     close : str
         [**+b**\|\ **d**\|\ **D**][**+xl**\|\ **r**\|\ *x0*]\
         [**+yl**\|\ **r**\|\ *y0*][**+p**\ *pen*].
@@ -220,9 +222,14 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
             )
         extra_arrays.append(sizes)
 
-    if "t" in kwargs and is_nonstr_iter(kwargs["t"]):
-        extra_arrays.append(kwargs["t"])
-        kwargs["t"] = ""
+    for flag in ["I", "t"]:
+        if flag in kwargs and is_nonstr_iter(kwargs[flag]):
+            if kind != "vectors":
+                raise GMTInvalidInput(
+                    f"Can't use arrays for {plot.aliases[flag]} if data is matrix or file."
+                )
+            extra_arrays.append(kwargs[flag])
+            kwargs[flag] = ""
 
     with Session() as lib:
         # Choose how data will be passed in to the module

pygmt/tests/baseline/test_plot_varying_intensity.png.dvc

@@ -0,0 +1,4 @@
+outs:
+- md5: f4b44bcae2670fac23c6e43324bda8fe
+  size: 16182
+  path: test_plot_varying_intensity.png

pygmt/tests/test_plot.py

@@ -93,30 +93,19 @@ def test_plot_fail_no_data(data):
         )
 
 
-def test_plot_fail_size_color(data):
+def test_plot_fail_color_size_intensity(data):
     """
-    Should raise an exception if array sizes and color are used with matrix.
+    Should raise an exception if array color, sizes and intensity are used with
+    matrix.
     """
     fig = Figure()
+    kwargs = dict(data=data, region=region, projection="X10c", frame="afg")
     with pytest.raises(GMTInvalidInput):
-        fig.plot(
-            data=data,
-            region=region,
-            projection="X4i",
-            style="c0.2c",
-            color=data[:, 2],
-            frame="afg",
-        )
+        fig.plot(style="c0.2c", color=data[:, 2], **kwargs)
     with pytest.raises(GMTInvalidInput):
-        fig.plot(
-            data=data,
-            region=region,
-            projection="X4i",
-            style="cc",
-            sizes=data[:, 2],
-            color="red",
-            frame="afg",
-        )
+        fig.plot(style="cc", sizes=data[:, 2], color="red", **kwargs)
+    with pytest.raises(GMTInvalidInput):
+        fig.plot(style="c0.2c", color="red", intensity=data[:, 2], **kwargs)
 
 
 @check_figures_equal()
@@ -231,6 +220,29 @@ def test_plot_colors_sizes_proj(data, region):
     return fig
 
 
+@pytest.mark.mpl_image_compare
+def test_plot_varying_intensity():
+    """
+    Plot the data with array-like intensity.
+    """
+    x = np.arange(-1, 1.1, 0.1)
+    y = np.zeros(x.size)
+    intensity = x
+
+    fig = Figure()
+    fig.plot(
+        x=x,
+        y=y,
+        region=[-1.1, 1.1, -0.5, 0.5],
+        projection="X15c/2c",
+        frame=["S", "xaf+lIntensity"],
+        style="c0.5c",
+        color="blue",
+        intensity=intensity,
+    )
+    return fig
+
+
 @check_figures_equal()
 def test_plot_transparency():
     """