WIP: Add Figure.directional_rose to plot a directional rose on map

doc/api/index.rst

@@ -27,6 +27,7 @@ Plotting map elements
     Figure.basemap
     Figure.coast
     Figure.colorbar
+    Figure.directional_rose
     Figure.hlines
     Figure.inset
     Figure.legend

pygmt/figure.py

@@ -435,6 +435,7 @@ def _repr_html_(self) -> str:
         coast,
         colorbar,
         contour,
+        directional_rose,
         grdcontour,
         grdimage,
         grdview,

pygmt/src/__init__.py

@@ -10,6 +10,7 @@
 from pygmt.src.config import config
 from pygmt.src.contour import contour
 from pygmt.src.dimfilter import dimfilter
+from pygmt.src.directional_rose import directional_rose
 from pygmt.src.filter1d import filter1d
 from pygmt.src.grd2cpt import grd2cpt
 from pygmt.src.grd2xyz import grd2xyz

pygmt/src/basemap.py

@@ -2,6 +2,7 @@
 basemap - Plot base maps and frames.
 """
 
+import warnings
 from typing import Literal
 
 from pygmt.alias import AliasSystem
@@ -82,8 +83,11 @@ def basemap(
         [Default is ``"4p/-4p"``] and shade sets the fill style to use for
         shading [Default is ``"gray50"``].
     rose : str
-        Draw a map directional rose on the map at the location defined by
-        the reference and anchor points.
+        Draw a map directional rose on the map.
+
+        .. deprecated:: v0.17.0
+
+           Use :py:func:`pygmt.Figure.directional_rose` instead.
     compass : str
         Draw a map magnetic rose on the map at the location defined by the
         reference and anchor points.
@@ -95,6 +99,14 @@ def basemap(
     """
     self._activate_figure()
 
+    if kwargs.get("Td"):
+        warnings.warn(
+            "Parameter 'rose' is deprecated and will be removed in a future version. "
+            "Use 'Figure.directional_rose' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
     aliasdict = AliasSystem().add_common(
         J=projection,
         V=verbose,

pygmt/src/directional_rose.py

@@ -0,0 +1,124 @@
+"""
+directional_rose - Add a map directional rose.
+"""
+
+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.helpers import build_arg_list
+
+
+def directional_rose(
+    self,
+    position: Sequence[str | float] | AnchorCode,
+    position_type: Literal[
+        "mapcoords",
+        "boxcoords",
+        "plotcoords",
+        "inside",
+        "outside",
+    ] = "plotcoords",
+    width: float | str | None = None,
+    anchor: AnchorCode | None = None,
+    anchor_offset: Sequence[float | str] | None = None,
+    label: Sequence[str] | bool = False,
+    fancy: Literal[1, 2, 3] | bool = False,
+    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
+    | bool = False,
+    transparency: float | None = None,
+):
+    r"""
+    Add a directional rose on the map.
+
+    The directional rose is plotted at the location defined by the reference point
+    (specified by the **position** and *position_type** parameters) and anchor point
+    (set by the **anchor** and **anchor_offset** parameters).
+
+    Parameters
+    ----------
+    position/position_type
+        Reference point on the map for the directional rose. The meaning of the
+        **position** parameter depends on the **position_type** parameter:
+
+        - ``"mapcoords"``: **position** is given as (x, y) in user coordinates.
+        - ``"boxcoords"``: **position** is given as (nx, ny) in normalized coordinates,
+          where (0, 0) is the lower-left corner and (1, 1) is the upper-right corner of
+          the plot bounding box.
+        - ``"plotcoords"``: **position** is given as (x, y) in plot coordinates, i.e.,
+          the distances in inches, centimeters, or points from the lower left plot
+          origin.
+        - ``"inside"`` or ``"outside"``: **position** is the justification code, meaning
+          the anchor point of the rose is inside or outside the plot bounding box.
+    anchor
+        The anchor point of the rose, set by a 2-character justification code.
+        The default value depends on the **position_type** parameter.
+
+        - ``position_type="inside"``, **anchor** defaults to the same as **position**.
+        - ``position_type="outside"``, **anchor** defaults to the mirror opposite of
+          **position**.
+        - Otherwise, **anchor** defaults to ``"MC"`` (middle center).
+    anchor_offset
+        *offset* or (*offset_x*, *offset_y*).
+        Offset the anchor point by *offset_x* and *offset_y*. If a single value *offset*
+        is given, *offset_y* = *offset_x* = *offset*.
+    width
+        Width of the rose in plot coordinates (append **i** (inch),
+        **cm** (centimeters), or **p** (points)), or append % for a size in percentage
+        of map width [Default is 10 %].
+    label
+        A sequence of four strings to label the cardinal points W,E,S,N. Use an empty
+        string to skip a specific label. If set to ``True``, use the default labels
+        ``["W", "E", "S", "N"]``.
+    fancy
+        Get a fancy rose. The fanciness level can be set to 1, 2, or 3:
+
+        - Level 1 draws the two principal E-W, N-S orientations
+        - Level 2 adds the two intermediate NW-SE and NE-SW orientations
+        - Level 3 adds the four minor orientations WNW-ESE, NNW-SSE, NNE-SSW, and
+          ENE-WSW
+
+        If set to ``True``, it defaults to level 1.
+    {perspective}
+    {verbose}
+    {transparency}
+
+    Examples
+    --------
+    >>> import pygmt
+    >>> fig = pygmt.Figure()
+    >>> fig.basemap(region=[0, 80, -30, 30], projection="M10c", frame=True)
+    >>> fig.directional_rose(position=(10, 10), position_type="mapcoords")
+    >>> fig.show()
+    """
+    self._activate_figure()
+
+    aliasdict = AliasSystem(
+        Td=[
+            Alias(
+                position_type,
+                name="position_type",
+                mapping={
+                    "mapcoords": "g",
+                    "boxcoords": "n",
+                    "plotcoords": "x",
+                    "inside": "j",
+                    "outside": "J",
+                },
+            ),
+            Alias(position, name="position", sep="/", size=2),
+            Alias(fancy, name="fancy", prefix="+f"),  # +F is not supported yet.
+            Alias(anchor, name="anchor", prefix="+j"),
+            Alias(label, name="label", prefix="+l", sep=",", size=4),
+            Alias(anchor_offset, name="anchor_offset", prefix="+o", sep="/", size=2),
+            Alias(width, name="width", prefix="+w"),
+        ],
+    ).add_common(
+        V=verbose,
+        t=transparency,
+    )
+
+    with Session() as lib:
+        lib.call_module(module="basemap", args=build_arg_list(aliasdict))

pygmt/tests/baseline/test_directional_rose_complex.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 9f1971f6e2b5b87d42f21d7410149793
+  size: 14718
+  hash: md5
+  path: test_directional_rose_complex.png

pygmt/tests/test_basemap.py

@@ -94,9 +94,16 @@ def test_basemap_rose():
     Create a map with a rose.
     """
     fig = Figure()
-    fig.basemap(
-        region=[127.5, 128.5, 26, 27], projection="H15c", frame=True, rose="jMC+w5c"
-    )
+    with pytest.warns(
+        UserWarning,
+        match=(
+            "The 'rose' parameter is deprecated and will be removed in a future "
+            "release. Please use the 'directional_rose' method instead."
+        ),
+    ):
+        fig.basemap(
+            region=[127.5, 128.5, 26, 27], projection="H15c", frame=True, rose="jMC+w5c"
+        )
     return fig
 
 

pygmt/tests/test_directional_rose.py

@@ -0,0 +1,36 @@
+"""
+Test Figure.directional_rose.
+"""
+
+import pytest
+from pygmt import Figure
+
+
+@pytest.mark.mpl_image_compare(filename="test_basemap_rose.png")
+def test_directional_rose():
+    """
+    Test the Figure.directional_rose method.
+    """
+    fig = Figure()
+    fig.basemap(region=[127.5, 128.5, 26, 27], projection="H15c", frame=True)
+    fig.directional_rose(position="MC", position_type="inside", width="5c")
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_directional_rose_complex():
+    """
+    Test the Figure.directional_rose method with more parameters.
+    """
+    fig = Figure()
+    fig.basemap(region=[0, 80, -30, 30], projection="M10c", frame=True)
+    fig.directional_rose(
+        position=(50, 0),
+        position_type="mapcoords",
+        width="1c",
+        label=["", "", "", "N"],
+        fancy=2,
+        anchor_offset=(1, 1),
+        justify="MC",
+    )
+    return fig

pygmt/tests/test_inset.py

@@ -29,5 +29,6 @@ def test_inset_context_manager():
     fig.basemap(region=[-74, -69.5, 41, 43], projection="M9c", frame=True)
     with fig.inset(position="jBL+w3c+o0.2c", margin=0, box="+pblack"):
         fig.basemap(region=[-80, -65, 35, 50], projection="M3c", frame="afg")
-    fig.basemap(rose="jTR+w3c")  # Pass rose argument with basemap after the inset
+    # Plot an rose after the inset
+    fig.directional_rose(position="TR", position_type="inside", width="3c")
     return fig