Add the shading parameter to colorbar() in base_plotting.py (#752)

* Add the shading parameter to colorbar() in base_plotting.py
* Update pygmt/tests/test_colorbar.py

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

Author: willschlitzer

pygmt/base_plotting.py

@@ -153,14 +153,15 @@ def coast(self, **kwargs):
         D="position",
         F="box",
         G="truncate",
+        I="shading",
         W="scale",
         V="verbose",
         X="xshift",
         Y="yshift",
         p="perspective",
         t="transparency",
     )
-    @kwargs_to_strings(R="sequence", G="sequence", p="sequence")
+    @kwargs_to_strings(R="sequence", G="sequence", I="sequence", p="sequence")
     def colorbar(self, **kwargs):
         """
         Plot a gray or color scale-bar on maps.
@@ -223,6 +224,11 @@ def colorbar(self, **kwargs):
         scale : float
             Multiply all z-values in the CPT by the provided scale. By default
             the CPT is used as is.
+        shading : str or list or bool
+            Add illumination effects. Passing a single numerical value sets the range
+            of intensities from -value to +value. If not specified, 1 is used.
+            Alternatively, set ``shading=[low, high]`` to specify an asymmetric
+            intensity range from *low* to *high*. The default is no illumination.
         {V}
         {XY}
         {p}

pygmt/tests/test_colorbar.py

@@ -153,3 +153,63 @@ def test_colorbar_scaled_z_values():
     fig = Figure()
     fig.colorbar(cmap="rainbow", scale=0.1, position="x0c/0c+w2c/0.5c")
     return fig
+
+
+@check_figures_equal()
+def test_colorbar_shading_boolean():
+    """
+    Create colorbar and set shading with a Boolean value
+    """
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.basemap(R="0/10/0/10", J="X15c", B="a")
+    fig_ref.colorbar(C="geo", I="")
+
+    fig_test.basemap(region=[0, 10, 0, 10], projection="X15c", frame="a")
+    fig_test.colorbar(cmap="geo", shading=True)
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_colorbar_shading_float():
+    """
+    Create colorbar and set shading with a single float variable
+    """
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.basemap(R="0/10/0/10", J="X15c", B="a")
+    fig_ref.colorbar(C="geo", I=0.5)
+
+    fig_test.basemap(region=[0, 10, 0, 10], projection="X15c", frame="a")
+    fig_test.colorbar(cmap="geo", shading=0.5)
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_colorbar_shading_string():
+    """
+    Create colorbar and set shading by passing the low/high values as a string
+    """
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.basemap(R="0/10/0/10", J="X15c", B="a")
+    fig_ref.colorbar(C="geo", I="-0.7/0.2")
+
+    fig_test.basemap(region=[0, 10, 0, 10], projection="X15c", frame="a")
+    fig_test.colorbar(cmap="geo", shading="-0.7/0.2")
+    return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_colorbar_shading_list():
+    """
+    Create colorbar and set shading by passing the high/low values as a list
+    """
+    fig_ref, fig_test = Figure(), Figure()
+    # Use single-character arguments for the reference image
+    fig_ref.basemap(R="0/10/0/10", J="X15c", B="a")
+    fig_ref.colorbar(C="geo", I="-0.7/0.2")
+
+    fig_test.basemap(region=[0, 10, 0, 10], projection="X15c", frame="a")
+    fig_test.colorbar(cmap="geo", shading=[-0.7, 0.2])
+    return fig_ref, fig_test