Allow passing an array as intensity for plot

pygmt/src/plot.py

@@ -143,11 +143,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
+    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 [None]. If
-        using ``intensity=True``, we will instead read *intens* from the
+        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*].
@@ -218,9 +220,16 @@ 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(
+                    "Can't use arrays for {} if data is matrix or file.".format(
+                        plot.aliases[flag]
+                    )
+                )
+            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: 31830242b87fd43409f4fee86ad78c16
+  size: 20919
+  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, 10)
+    y = np.arange(1, 10)
+    intensity = np.linspace(-1, 1, len(x))
+
+    fig = Figure()
+    fig.plot(
+        x=x,
+        y=y,
+        region=[0, 10, 0, 10],
+        projection="X10c",
+        frame=True,
+        style="c0.5c",
+        color="blue",
+        intensity=intensity,
+    )
+    return fig
+
+
 @check_figures_equal()
 def test_plot_transparency():
     """