Updates

Author: seisman

pygmt/src/directional_rose.py

@@ -22,30 +22,45 @@ def directional_rose(
         "outside",
     ] = "plotcoords",
     width: float | str | None = None,
-    justify: AnchorCode | 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,
 ):
     r"""
-    Add a directional rose to the map.
+    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
-        Location of the directional rose. The actual meaning of this parameter depends
-        on the ``position_type`` parameter.
+        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,
+        - ``"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.
-        - ``"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"``: *position* is given as a two-character justification code,
-          meaning the anchor point of the rose is inside the plot bounding box.
-        - ``"outside"``: *position* is given as a two-character justification code, but
-          the rose is outside the plot bounding box.
+          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
@@ -63,15 +78,6 @@ def directional_rose(
           ENE-WSW
 
         If set to ``True``, it defaults to level 1.
-    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*.
-    justify
-        Set the anchor point. Specify a two-character (order independent) code. Choose
-        from vertical **T**\(op), **M**\(iddle), or **B**\(ottom) and horizontal
-        **L**\(eft), **C**\(entre), or **R**\(ight).
-
     {perspective}
     {verbose}
     {transparency}
@@ -100,11 +106,11 @@ def directional_rose(
                 },
             ),
             Alias(position, name="position", sep="/", size=2),
-            Alias(width, name="width", prefix="+w"),
-            Alias(fancy, name="fancy", prefix="+f"),
-            Alias(justify, name="justify", prefix="+j"),
+            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"),
         ],
     )