Alias box (F) for colorbar

Including tests for controlling how the border around the color scalebar is styled.

Author: weiji14

pygmt/base_plotting.py

@@ -126,7 +126,7 @@ def coast(self, **kwargs):
             lib.call_module("coast", build_arg_string(kwargs))
 
     @fmt_docstring
-    @use_alias(R="region", J="projection", B="frame", C="cmap", D="position")
+    @use_alias(R="region", J="projection", B="frame", C="cmap", D="position", F="box")
     @kwargs_to_strings()
     def colorbar(self, **kwargs):
         """
@@ -162,6 +162,26 @@ def colorbar(self, **kwargs):
             corner (BL), but this can be changed by appending +j followed by a 2-char
             justification code justify.
 
+        box (F) : bool or str
+            ``[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/]
+            [shade]]]``.
+            If set to True, draws a rectangular border around the color scale.
+            Alternatively, specify a different pen with +ppen.
+            Add +gfill to fill the scale panel [no fill].
+            Append +cclearance where clearance is either gap, xgap/ygap, or
+            lgap/rgap/bgap/tgap where these items are uniform, separate in x- and
+            y-direction, or individual side spacings between scale and border.
+            Append +i to draw a secondary, inner border as well. We use a uniform gap
+            between borders of 2p and the MAP_DEFAULTS_PEN unless other values are
+            specified.
+            Append +r to draw rounded rectangular borders instead, with a 6p corner
+            radius. You can override this radius by appending another value.
+            Finally, append +s to draw an offset background shaded region. Here, dx/dy
+            indicates the shift relative to the foreground frame [4p/-4p] and shade sets
+            the fill style to use for shading [gray50].
+
+
+
         {aliases}
         """
         kwargs = self._preprocess(**kwargs)

pygmt/tests/baseline/test_colorbar_box.png

@@ -57,3 +57,74 @@ def test_colorbar_positioned_using_normalized_coords():
     fig.basemap(region=[2, 4, 6, 8], projection="t0/2c", frame=True)
     fig.colorbar(cmap="rainbow", position="n0.75/0.25+w2c")
     return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_box():
+    """
+    Create colorbar with box around it.
+    """
+    fig = Figure()
+    fig.colorbar(cmap="rainbow", box=True, position="x0c/0c+w1c/0.5c")
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_box_with_pen():
+    """
+    Create colorbar with box that has a different colored pen.
+    """
+    fig = Figure()
+    fig.colorbar(cmap="rainbow", box="+porange", position="x0c/0c+w1c/0.5c")
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_box_with_fill():
+    """
+    Create colorbar with box that has a different colored fill.
+    """
+    fig = Figure()
+    fig.colorbar(cmap="rainbow", box="+gorange", position="x0c/0c+w1c/0.5c")
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_box_with_clearance():
+    """
+    Create colorbar with box that has an x-clearance of 0.8cm and y-clearance of 0.4cm.
+    """
+    fig = Figure()
+    fig.colorbar(cmap="rainbow", box="+c0.8c/0.4c+porange", position="x0c/0c+w1c/0.5c")
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_box_with_secondary_border():
+    """
+    Create colorbar with box that has a secondary, inner border in addition to the main
+    primary, outer border.
+    """
+    fig = Figure()
+    fig.colorbar(cmap="rainbow", box="+porange+imagenta", position="x0c/0c+w1c/0.5c")
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_box_with_rounded_corners():
+    """
+    Create colorbar with box that has rounded corners.
+    """
+    fig = Figure()
+    fig.colorbar(cmap="rainbow", box="+porange+r", position="x0c/0c+w1c/0.5c")
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_box_with_offset_background():
+    """
+    Create colorbar with box and an offset background shaded region.
+    """
+    fig = Figure()
+    fig.colorbar(cmap="rainbow", box="+s5p/-5p", position="x0c/0c+w1c/0.5c")
+    return fig