Figure.colorbar: Add position/length/width and more parameters to specify colorbar position and properties (#4048)

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

Author: seisman

pygmt/src/_common.py

@@ -345,7 +345,7 @@ def _parse_position(
         case str() if position in _valid_anchors:  # Anchor code
             position = Position(position, cstype="inside")
         case str():  # Raw GMT command string.
-            if any(v is not None for v in kwdict.values()):
+            if any(v is not None and v is not False for v in kwdict.values()):
                 msg = (
                     "Parameter 'position' is given with a raw GMT command string, and "
                     f"conflicts with parameters {', '.join(repr(c) for c in kwdict)}."

pygmt/src/colorbar.py

@@ -5,31 +5,122 @@
 from collections.abc import Sequence
 from typing import Literal
 
+from pygmt._typing import AnchorCode
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
+from pygmt.exceptions import GMTValueError
 from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
-from pygmt.params import Box
+from pygmt.helpers.utils import is_nonstr_iter
+from pygmt.params import Box, Position
+from pygmt.src._common import _parse_position
 
 __doctest_skip__ = ["colorbar"]
 
 
+def _alias_option_D(  # noqa: N802, PLR0913
+    position=None,
+    length=None,
+    width=None,
+    orientation=None,
+    reverse=False,
+    nan=False,
+    nan_position=None,
+    fg_triangle=False,
+    bg_triangle=False,
+    triangle_height=None,
+    move_text=None,
+    label_as_column=False,
+):
+    """
+    Return a list of Alias objects for the -D option.
+    """
+    # Build the +e modifier from fg_triangle/bg_triangle/triangle_height
+    if fg_triangle and bg_triangle:
+        modifier_e = ""
+    elif fg_triangle:
+        modifier_e = "f"
+    elif bg_triangle:
+        modifier_e = "b"
+    else:
+        modifier_e = None
+    if modifier_e is not None and triangle_height is not None:
+        modifier_e = f"{modifier_e}{triangle_height}"
+
+    # Build the +m modifier from move_text/label_as_column
+    modifier_m = None
+    if move_text or label_as_column:
+        modifier_m = ""
+
+        _valids = {"annotations", "label", "unit"}
+        if move_text is not None:
+            if (isinstance(move_text, str) and move_text not in _valids) or (
+                is_nonstr_iter(move_text) and not all(v in _valids for v in move_text)
+            ):
+                raise GMTValueError(
+                    move_text,
+                    description="move_text",
+                    choices=_valids,
+                )
+            if isinstance(move_text, str):
+                modifier_m = move_text[0]
+            elif is_nonstr_iter(move_text):
+                modifier_m = "".join(item[0] for item in move_text)
+        if label_as_column:
+            modifier_m += "c"
+
+    return [
+        Alias(position, name="position"),
+        Alias(length, name="length", prefix="+w"),  # +wlength/width
+        Alias(width, name="width", prefix="/"),
+        Alias(
+            orientation,
+            name="orientation",
+            mapping={"horizontal": "+h", "vertical": "+v"},
+        ),
+        Alias(reverse, name="reverse", prefix="+r"),
+        Alias(
+            nan,
+            name="nan",
+            prefix="+n" if nan_position in {"start", None} else "+N",
+        ),
+        Alias(
+            modifier_e,
+            name="fg_triangle/bg_triangle/triangle_height",
+            prefix="+e",
+        ),
+        Alias(modifier_m, name="move_text/label_as_column", prefix="+m"),
+    ]
+
+
 @fmt_docstring
-@use_alias(C="cmap", D="position", L="equalsize", Z="zfile")
+@use_alias(C="cmap", L="equalsize", Z="zfile")
 def colorbar(  # noqa: PLR0913
     self,
+    position: Position | Sequence[float | str] | AnchorCode | None = None,
+    length: float | str | None = None,
+    width: float | str | None = None,
+    orientation: Literal["horizontal", "vertical"] | None = None,
+    reverse: bool = False,
+    nan: bool = False,
+    nan_position: Literal["start", "end"] | None = None,
+    bg_triangle: bool = False,
+    fg_triangle: bool = False,
+    triangle_height: float | None = None,
+    move_text: Literal["annotations", "label", "unit"] | Sequence[str] | None = None,
+    label_as_column: bool = False,
+    box: Box | bool = False,
     truncate: Sequence[float] | None = None,
     shading: float | Sequence[float] | bool = False,
     log: bool = False,
     scale: float | None = None,
     projection: str | None = None,
-    box: Box | bool = False,
-    frame: str | Sequence[str] | bool = False,
     region: Sequence[float | str] | str | None = None,
+    frame: str | Sequence[str] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    transparency: float | None = None,
     perspective: float | Sequence[float] | str | bool = False,
+    transparency: float | None = None,
     **kwargs,
 ):
     r"""
@@ -70,33 +161,70 @@ def colorbar(  # noqa: PLR0913
        - p = perspective
        - t = transparency
 
+    .. hlist::
+       :columns: 1
+
+       - D = position, **+w**: length/width, **+h**/**+v**: orientation,
+         **+r**: reverse, **+n**: nan/nan_position,
+         **+e**: fg_triangle/bg_triangle/triangle_height,
+         **+m**: move_text/label_as_column
+
     Parameters
     ----------
-    frame : str or list
-        Set colorbar boundary frame, labels, and axes attributes.
     $cmap
-    position : str
-        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
-        [**+w**\ *length*\ [/\ *width*]]\ [**+e**\ [**b**\|\ **f**][*length*]]\
-        [**+h**\|\ **v**][**+j**\ *justify*]\
-        [**+m**\ [**a**\|\ **c**\|\ **l**\|\ **u**]]\
-        [**+n**\ [*txt*]][**+o**\ *dx*\ [/*dy*]].
-        Define the reference point on the map for the color scale using one of
-        four coordinate systems: (1) Use **g** for map (user) coordinates, (2)
-        use **j** or **J** for setting *refpoint* via a
-        :doc:`2-character justification code </techref/justification_codes>`
-        that refers to the (invisible) map domain rectangle,
-        (3) use **n** for normalized (0-1) coordinates, or (4) use **x** for
-        plot coordinates (inches, cm, etc.). All but **x** requires both
-        ``region`` and ``projection`` to be specified. Append **+w** followed
-        by the length and width of the colorbar. If width is not specified
-        then it is set to 4% of the given length. Give a negative length to
-        reverse the scale bar. Append **+h** to get a horizontal scale
-        [Default is vertical (**+v**)]. By default, the anchor point on the
-        scale is assumed to be the bottom left corner (**BL**), but this can
-        be changed by appending **+j** followed by a
-        :doc:`2-character justification code </techref/justification_codes>`
-        *justify*.
+    position
+        Position of the colorbar on the plot. It can be specified in multiple ways:
+
+        - A :class:`pygmt.params.Position` object to fully control the reference point,
+          anchor point, and offset.
+        - A sequence of two values representing the x- and y-coordinates in plot
+          coordinates, e.g., ``(1, 2)`` or ``("1c", "2c")``.
+        - A :doc:`2-character justification code </techref/justification_codes>` for a
+          position inside the plot, e.g., ``"TL"`` for Top Left corner inside the plot.
+
+        If not specified, defaults to bottom-center outside of the plot.
+    length
+    width
+        Length and width of the colorbar. If length is given with a unit ``%`` then it
+        is in percentage of the corresponding plot side dimension (i.e., plot width for
+        a horizontal colorbar, or plot height for a vertical colorbar). If width is
+        given with unit ``%`` then it is in percentage of the bar length. [Length
+        defaults to 80% of the corresponding plot side dimension, and width defaults
+        to 4% of the bar length].
+    orientation
+        Set the colorbar orientation to either ``"horizontal"`` or ``"vertical"``.
+        [Default is vertical, unless ``position`` is set to bottom-center or top-center
+        with ``cstype="outside"`` or ``cstype="inside"``, then horizontal is the
+        default].
+    reverse
+        Reverse the positive direction of the bar.
+    nan
+        Draw a rectangle filled with the NaN color (via the **N** entry in the CPT or
+        :gmt-term:`COLOR_NAN` if no such entry) at the start or end of the colorbar
+        (controlled via ``nan_position``). If a string is given, use that string as the
+        label for the NaN color.
+    nan_position
+        Set the position of the NaN rectangle. Choose either ``"start"`` or ``"end"`` to
+        place the NaN color rectangle at the start or end of the colorbar [Default is
+        ``"start"``].
+    bg_triangle
+    fg_triangle
+        If ``True``, draw triangles for the back- or foreground colors [Default is
+        no triangles]. The back- and/or foreground colors are taken from the **B**
+        and **F** entries in the CPT. If no such entries exist, then the system default
+        colors for **B** and **F** are used instead (:gmt-term:`COLOR_BACKGROUND` and
+        :gmt-term:`COLOR_FOREGROUND`).
+    triangles_height
+        Height of the triangles for back- and foreground colors [Default is half
+        of the bar width].
+    move_text
+        Move text (annotations, label, and unit) to opposite side. Accept a sequence of
+        strings containing one or more of ``"annotations"``, ``"label"``, and
+        ``"unit"``. The default placements of these texts depend on the colorbar
+        orientation and position.
+    label_as_column
+        Print a vertical label as a column of characters (does not work with special
+        characters).
     box
         Draw a background box behind the colorbar. If set to ``True``, a simple
         rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box
@@ -138,6 +266,10 @@ def colorbar(  # noqa: PLR0913
         may be in plot distance units or given as relative fractions and will
         be automatically scaled so that the sum of the widths equals the
         requested colorbar length.
+    $projection
+    $region
+    frame
+        Set colorbar boundary frame, labels, and axes attributes.
     $verbose
     $panel
     $perspective
@@ -162,7 +294,39 @@ def colorbar(  # noqa: PLR0913
     """
     self._activate_figure()
 
+    position = _parse_position(
+        position,
+        kwdict={
+            "length": length,
+            "width": width,
+            "orientation": orientation,
+            "reverse": reverse,
+            "nan": nan,
+            "nan_position": nan_position,
+            "bg_triangle": bg_triangle,
+            "fg_triangle": fg_triangle,
+            "triangle_height": triangle_height,
+            "move_text": move_text,
+            "label_as_column": label_as_column,
+        },
+        default=None,  # Use GMT's default behavior if position is not provided.
+    )
+
     aliasdict = AliasSystem(
+        D=_alias_option_D(
+            position=position,
+            length=length,
+            width=width,
+            orientation=orientation,
+            reverse=reverse,
+            nan=nan,
+            nan_position=nan_position,
+            bg_triangle=bg_triangle,
+            fg_triangle=fg_triangle,
+            triangle_height=triangle_height,
+            move_text=move_text,
+            label_as_column=label_as_column,
+        ),
         F=Alias(box, name="box"),
         G=Alias(truncate, name="truncate", sep="/", size=2),
         I=Alias(shading, name="shading", sep="/", size=2),

pygmt/tests/test_colorbar.py

@@ -4,6 +4,10 @@
 
 import pytest
 from pygmt import Figure
+from pygmt.alias import AliasSystem
+from pygmt.exceptions import GMTInvalidInput
+from pygmt.params.position import Position
+from pygmt.src.colorbar import _alias_option_D
 
 
 @pytest.mark.benchmark
@@ -13,7 +17,12 @@ def test_colorbar():
     Create a simple colorbar.
     """
     fig = Figure()
-    fig.colorbar(cmap="gmt/rainbow", position="x0c/0c+w4c", frame=True)
+    fig.colorbar(
+        cmap="gmt/rainbow",
+        position=Position((0, 0), cstype="plotcoords"),
+        length=4,
+        frame=True,
+    )
     return fig
 
 
@@ -26,3 +35,91 @@ def test_colorbar_shading_list():
     fig.basemap(region=[0, 10, 0, 2], projection="X10c/2c", frame="a")
     fig.colorbar(cmap="gmt/geo", shading=[-0.7, 0.2], frame=True)
     return fig
+
+
+def test_colorbar_alias_D():  # noqa: N802
+    """
+    Test the parameters for the -D option.
+    """
+
+    def alias_wrapper(**kwargs):
+        """
+        A wrapper function for testing the parameters of -D option.
+        """
+        return AliasSystem(D=_alias_option_D(**kwargs)).get("D")
+
+    argstr = alias_wrapper(position=Position("TL", offset=0.2), length=4, width=0.5)
+    assert argstr == "jTL+o0.2+w4/0.5"
+
+    assert alias_wrapper(orientation="horizontal") == "+h"
+    assert alias_wrapper(orientation="vertical") == "+v"
+
+    assert alias_wrapper(reverse=True) == "+r"
+
+    assert alias_wrapper(nan=True) == "+n"
+    assert alias_wrapper(nan=True, nan_position="end") == "+N"
+
+    assert alias_wrapper(fg_triangle=True, bg_triangle=True) == "+e"
+    assert alias_wrapper(fg_triangle=True) == "+ef"
+    assert alias_wrapper(bg_triangle=True) == "+eb"
+    assert alias_wrapper(fg_triangle=True, triangle_height=0.4) == "+ef0.4"
+    argstr = alias_wrapper(fg_triangle=True, bg_triangle=True, triangle_height=0.3)
+    assert argstr == "+e0.3"
+
+    assert alias_wrapper(move_text="annotations") == "+ma"
+    assert alias_wrapper(move_text="label") == "+ml"
+    assert alias_wrapper(move_text="unit") == "+mu"
+    assert alias_wrapper(move_text=["annotations", "label", "unit"]) == "+malu"
+    assert alias_wrapper(label_as_column=True) == "+mc"
+    argstr = alias_wrapper(move_text=["annotations", "label"], label_as_column=True)
+    assert argstr == "+malc"
+
+    argstr = alias_wrapper(
+        position=Position("BR", offset=(0.1, 0.2)),
+        length=5,
+        width=0.4,
+        orientation="vertical",
+        reverse=True,
+        nan=True,
+        nan_position="start",
+        bg_triangle=True,
+        triangle_height=0.2,
+        move_text=["annotations", "unit"],
+        label_as_column=True,
+    )
+    assert argstr == "jBR+o0.1/0.2+w5/0.4+v+r+n+eb0.2+mauc"
+
+
+@pytest.mark.mpl_image_compare(filename="test_colorbar.png")
+def test_colorbar_position_deprecated_syntax():
+    """
+    Check that passing the deprecated GMT CLI syntax string to 'position' works.
+    """
+    fig = Figure()
+    fig.colorbar(cmap="gmt/rainbow", position="x0/0+w4c", frame=True)
+    return fig
+
+
+def test_image_position_mixed_syntax():
+    """
+    Test that mixing deprecated GMT CLI syntax string with new parameters.
+    """
+    fig = Figure()
+    with pytest.raises(GMTInvalidInput):
+        fig.colorbar(cmap="gmt/rainbow", position="x0/0", length="4c")
+    with pytest.raises(GMTInvalidInput):
+        fig.colorbar(cmap="gmt/rainbow", position="x0/0", width="0.5c")
+    with pytest.raises(GMTInvalidInput):
+        fig.colorbar(cmap="gmt/rainbow", position="x0/0", orientation="horizontal")
+    with pytest.raises(GMTInvalidInput):
+        fig.colorbar(cmap="gmt/rainbow", position="x0/0", reverse=True)
+    with pytest.raises(GMTInvalidInput):
+        fig.colorbar(cmap="gmt/rainbow", position="x0/0", nan=True)
+    with pytest.raises(GMTInvalidInput):
+        fig.colorbar(
+            cmap="gmt/rainbow", position="x0/0", fg_triangle=True, bg_triangle=True
+        )
+    with pytest.raises(GMTInvalidInput):
+        fig.colorbar(cmap="gmt/rainbow", position="x0/0", move_text="label")
+    with pytest.raises(GMTInvalidInput):
+        fig.colorbar(cmap="gmt/rainbow", position="x0/0", label_as_column=True)