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

@@ -413,6 +413,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

@@ -11,7 +11,7 @@
 
 
 @fmt_docstring
-@use_alias(F="box", Td="rose", Tm="compass", f="coltypes")
+@use_alias(F="box", Tm="compass", f="coltypes")
 def basemap(  # noqa: PLR0913
     self,
     projection: str | None = None,
@@ -20,6 +20,7 @@ def basemap(  # noqa: PLR0913
     frame: str | Sequence[str] | bool = False,
     region: Sequence[float | str] | str | None = None,
     map_scale: str | None = None,
+    rose: str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
@@ -41,6 +42,7 @@ def basemap(  # noqa: PLR0913
     ``basemap`` module:
 
     - :meth:`pygmt.Figure.scalebar`: Add a scale bar on the plot.
+    - :meth:``pygmt.Figure.directional_rose`: Add a directional rose on the plot.
 
     Full GMT docs at :gmt-docs:`basemap.html`.
 
@@ -51,6 +53,7 @@ def basemap(  # noqa: PLR0913
        - JZ = zsize
        - L = map_scale
        - R = region
+       - Td = rose
        - V = verbose
        - c = panel
        - p = perspective
@@ -73,6 +76,15 @@ def basemap(  # noqa: PLR0913
             which provides a more comprehensive and flexible API for adding scale bars
             to plots. This parameter still accepts raw GMT CLI strings for the ``-L``
             option of the ``basemap`` module for backward compatibility.
+    rose
+        Draw a map directional rose on the map.
+
+        .. deprecated:: v0.19.0
+
+            This parameter is deprecated. Use :meth:`pygmt.Figure.directional_rose`
+            instead, which provides a more comprehensive and flexible API for adding
+            directional roses. This parameter still accepts raw GMT CLI strings for the
+            ``-Td`` option of the ``basemap`` module for backward compatibility.
     box : bool or str
         [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\
         [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]].
@@ -91,9 +103,6 @@ def basemap(  # noqa: PLR0913
         Here, *dx/dy* indicates the shift relative to the foreground frame
         [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.
     compass : str
         Draw a map magnetic rose on the map at the location defined by the
         reference and anchor points.
@@ -109,6 +118,7 @@ def basemap(  # noqa: PLR0913
         Jz=Alias(zscale, name="zscale"),
         JZ=Alias(zsize, name="zsize"),
         L=Alias(map_scale, name="map_scale"),  # Deprecated.
+        Td=Alias(rose, name="rose"),  # Deprecated.
     ).add_common(
         B=frame,
         J=projection,

pygmt/src/directional_rose.py

@@ -0,0 +1,104 @@
+"""
+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, fmt_docstring
+from pygmt.params import Box, Position
+from pygmt.src._common import _parse_position
+
+__doctest_skip__ = ["directional_rose"]
+
+
+@fmt_docstring
+def directional_rose(
+    self,
+    position: Position | Sequence[float | str] | AnchorCode | None = None,
+    width: float | str | None = None,
+    fancy: Literal[1, 2, 3] | bool = False,
+    labels: Sequence[str] | bool = False,
+    box: Box | bool = False,
+    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
+    | bool = False,
+    panel: int | Sequence[int] | bool = False,
+    perspective: str | bool = False,
+    transparency: float | None = None,
+):
+    """
+    Add a directional rose on the map.
+
+    Parameters
+    ----------
+    position
+        Position of the directional rose 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 the Bottom Left corner of the plot.
+    width
+        Width of the rose in plot coordinates, or append unit ``%`` for a size in
+        percentage of plot width [Default is 10%].
+    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``, defaults to level 1.
+    labels
+        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``, default labels are used
+        (``["W", "E", "S", "N"]`` for a fancy rose and ``["", "", "", "N"]`` for a
+        simple rose).
+    box
+        Draw a background box behind the directional rose. If set to ``True``, a simple
+        rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box
+        appearance, pass a :class:`pygmt.params.Box` object to control style, fill, pen,
+        and other box properties.
+    $verbose
+    $panel
+    $perspective
+    $transparency
+
+    Examples
+    --------
+    >>> import pygmt
+    >>> fig = pygmt.Figure()
+    >>> fig.basemap(region=[0, 80, 0, 30], projection="M10c", frame=True)
+    >>> fig.directional_rose()
+    >>> fig.show()
+    """
+    self._activate_figure()
+
+    position = _parse_position(position, default=Position("BL", cstype="inside"))
+
+    aliasdict = AliasSystem(
+        F=Alias(box, name="box"),
+        Td=[
+            Alias(position, name="position"),
+            Alias(width, name="width", prefix="+w"),
+            Alias(fancy, name="fancy", prefix="+f"),
+            Alias(labels, name="labels", prefix="+l", sep=",", size=4),
+        ],
+    ).add_common(
+        V=verbose,
+        c=panel,
+        p=perspective,
+        t=transparency,
+    )
+
+    with Session() as lib:
+        lib.call_module(module="basemap", args=build_arg_list(aliasdict))

pygmt/tests/baseline/test_directional_rose.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: c1c167a826132bcdabc3b032438db01e
+  size: 8319
+  hash: md5
+  path: test_directional_rose.png

pygmt/tests/baseline/test_directional_rose_complex.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 7a7eabd0036dc9b744e54dfbc398fc6e
+  size: 9772
+  hash: md5
+  path: test_directional_rose_complex.png

pygmt/tests/baseline/test_directional_rose_fancy.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 7498ed12efd8b956a0fe13d18e0e3ea9
+  size: 8648
+  hash: md5
+  path: test_directional_rose_fancy.png

pygmt/tests/test_directional_rose.py

@@ -0,0 +1,45 @@
+"""
+Test Figure.directional_rose.
+"""
+
+import pytest
+from pygmt import Figure
+from pygmt.params import Position
+
+
+@pytest.mark.mpl_image_compare
+def test_directional_rose():
+    """
+    Test the Figure.directional_rose method with default position and width.
+    """
+    fig = Figure()
+    fig.basemap(region=[0, 80, 0, 30], projection="M10c", frame=True)
+    fig.directional_rose()
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_directional_rose_fancy():
+    """
+    Test the Figure.directional_rose method with the fancy style enabled.
+    """
+    fig = Figure()
+    fig.basemap(region=[0, 80, 0, 30], projection="M10c", frame=True)
+    fig.directional_rose(fancy=True)
+    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, 0, 30], projection="M10c", frame=True)
+    fig.directional_rose(
+        position=Position((50, 0), cstype="mapcoords", anchor="MC", offset=(1, 1)),
+        width="1c",
+        labels=["", "", "", "N"],
+        fancy=2,
+    )
+    return fig

pygmt/tests/test_inset.py

@@ -38,7 +38,8 @@ def test_inset_context_manager():
         position=Position("BL", offset=0.2), width="3c", clearance=0.2, box=True
     ):
         fig.basemap(region="g", projection="G47/-20/?", frame="afg")
-    fig.basemap(rose="jTR+w3c")  # Pass rose argument with basemap after the inset
+    # Plot a rose after the inset
+    fig.directional_rose(position="TR", width="3c")
     return fig