Clarify that the "transparency" parameter in plot/plot3d/text can be 1d array (#1265)

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

Author: 3 people

pygmt/src/plot.py

@@ -204,7 +204,7 @@ def plot(self, x=None, y=None, data=None, size=None, direction=None, **kwargs):
     {p}
     {t}
         *transparency* can also be a 1d array to set varying transparency
-        for symbols.
+        for symbols, but this option is only valid if using x/y.
     """
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
 

pygmt/src/plot3d.py

@@ -168,7 +168,7 @@ def plot3d(
     {p}
     {t}
         *transparency* can also be a 1d array to set varying transparency
-        for symbols.
+        for symbols, but this option is only valid if using x/y/z.
     """
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
 

pygmt/src/text.py

@@ -147,6 +147,8 @@ def text_(
     {f}
     {p}
     {t}
+        *transparency* can also be a 1d array to set varying transparency
+        for texts, but this option is only valid if using x/y/text.
     """
 
     # pylint: disable=too-many-locals

pygmt/tests/test_plot.py

@@ -91,10 +91,10 @@ def test_plot_fail_no_data(data):
         )
 
 
-def test_plot_fail_color_size_intensity(data):
+def test_plot_fail_1d_array_with_data(data):
     """
-    Should raise an exception if array color, size and intensity are used with
-    matrix.
+    Should raise an exception if array color, size, intensity and transparency
+    are used with matrix.
     """
     fig = Figure()
     kwargs = dict(data=data, region=region, projection="X10c", frame="afg")
@@ -104,6 +104,8 @@ def test_plot_fail_color_size_intensity(data):
         fig.plot(style="cc", size=data[:, 2], color="red", **kwargs)
     with pytest.raises(GMTInvalidInput):
         fig.plot(style="c0.2c", color="red", intensity=data[:, 2], **kwargs)
+    with pytest.raises(GMTInvalidInput):
+        fig.plot(style="c0.2c", color="red", transparency=data[:, 2] * 100, **kwargs)
 
 
 @pytest.mark.mpl_image_compare

pygmt/tests/test_plot3d.py

@@ -108,10 +108,10 @@ def test_plot3d_fail_no_data(data, region):
         )
 
 
-def test_plot3d_fail_color_size_intensity(data, region):
+def test_plot3d_fail_1d_array_with_data(data, region):
     """
-    Should raise an exception if array color, size and intensity are used with
-    matrix.
+    Should raise an exception if array color, size, intensity and transparency
+    are used with matrix.
     """
     fig = Figure()
     kwargs = dict(data=data, region=region, projection="X10c", frame="afg")
@@ -121,6 +121,8 @@ def test_plot3d_fail_color_size_intensity(data, region):
         fig.plot3d(style="cc", size=data[:, 2], color="red", **kwargs)
     with pytest.raises(GMTInvalidInput):
         fig.plot3d(style="cc", intensity=data[:, 2], color="red", **kwargs)
+    with pytest.raises(GMTInvalidInput):
+        fig.plot3d(style="cc", color="red", transparency=data[:, 2] * 100, **kwargs)
 
 
 @pytest.mark.mpl_image_compare