From 2ea20618ee3edae0718a5b39ea2843974739b608 Mon Sep 17 00:00:00 2001
From: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
Date: Wed, 23 Jul 2025 17:00:44 +0200
Subject: [PATCH 1/7] DOC: Add gallery example to usage of map roses

---
 examples/gallery/embellishments/map_roses.py | 148 +++++++++++++++++++
 1 file changed, 148 insertions(+)
 create mode 100644 examples/gallery/embellishments/map_roses.py

diff --git a/examples/gallery/embellishments/map_roses.py b/examples/gallery/embellishments/map_roses.py
new file mode 100644
index 00000000000..0c457da1c15
--- /dev/null
+++ b/examples/gallery/embellishments/map_roses.py
@@ -0,0 +1,148 @@
+r"""
+Directional map roses
+=========
+
+The ``rose`` parameter of the :meth:`pygmt.Figure.basemap` and
+:meth:`pygmt.Figure.coast` methods is used to add a directional map 
+rose to a map. This example shows how such a map rose can be customized:
+
+ - position: **g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**. Set the position
+   of the reference point. Choose from
+
+   - **g**: Give map coordinates as *longitude*\/\ *latitude*.
+   - **j**\|\ **J**: 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). Lower /
+     uppercase **j** / **J** mean inside / outside of the map bounding
+     box.
+   - **n**: Give normalized bounding box coordinates as *nx*\/\ *ny*.
+   - **x**: Give plot coordinates as *x*\/\ *y*.
+
+- width: **+w**: Set the width of the rose in plot coordinates (append
+  **i** (inch), **cm** (centimeters), or **p** (points).
+
+- fanciness: **+f**[level]: Get a “fancy” rose, and optionally specify the
+  level of fanciness. Level 1 draws the two principal E-W, N-S orientations,
+  2 adds the two intermediate NW-SE and NE-SW orientations, while 3 adds
+  the eight minor orientations WNW-ESE, NNW-SSE, NNE-SSW, and ENE-WSW
+  [default is 1].
+
+- justify: **+j**: 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).
+
+- label: **+l**[w,e,s,n]: Label the cardinal points W,E,S,N. Optionally,
+  append your own four comma-separated strings to override the default.
+  Skip a specific label by leaving it blank.
+
+- offset: **+o**\ *offset* or **+o**\ *xoffset*/\ *yoffset*: Give either a
+  common shift or individual shifts in x- (longitude) and y- (latitude)
+  directions.
+
+Colors of the map roses can be adjusted using :gmt-term:`MAP_DEFAULT_PEN`
+and :gmt-term:`MAP_TICK_PEN_PRIMARY` via :func:`pygmt.config`. Customizing
+label font and color can be done via :gmt-term:`FONT_TITLE`.
+"""
+
+fig = pygmt.Figure()
+
+region = [-5,5,-5,5]
+projection = "M?"
+
+with fig.subplot(
+    nrows=2, ncols=4, figsize=("20c", "10c"), sharex = True, sharey = True):
+
+    # Plain rose of 2.5 cm width showing arrow towards north, a cross
+    # indicating the cardinal directions, and corresponding label
+    with fig.set_panel(panel=0):
+        fig.basemap(region = region,
+           projection = projection,
+           rose = "g0/0+w2.5c+jCM+l",
+           frame = True)
+
+    # Fancy, 2.5 cm wide rose of level 1 and labels indicating the different
+    # directions
+    with fig.set_panel(panel=1):
+
+          fig.basemap(region = region,
+           projection = projection,
+           rose = "g0/0+w2.5c+f1+jCM+l",
+           frame = True)
+
+    # Fancy, 2.5 cm wide rose of level 2 abels indicating the different
+    # directions
+    with fig.set_panel(panel=2):
+
+          fig.basemap(region = region,
+           projection = projection,
+           rose = "g0/0+w2.5c+f2+l+jCM",
+           frame = True)
+        
+    # Fancy, 2.5 cm wide rose of level 3 abels indicating the different
+    # directions
+    with fig.set_panel(panel=3):
+
+          fig.basemap(region = region,
+           projection = projection,
+           rose = "g0/0+w2.5c+f3+l+jCM",
+           frame = True)
+
+
+    # Plain rose of 2.5 cm width showing arrow towards north, a cross
+    # indicating the cardinal directions, and corresponding label.
+    # Colors of the rose and labels are defined via
+    # MAP_TICK_PEN_PRIMARY and FONT_TITLE, respectively
+    with fig.set_panel(panel=4):
+
+        with pygmt.config(MAP_TICK_PEN_PRIMARY="purple",
+                          FONT_TITLE="8p,darkmagenta"):
+
+        
+            fig.basemap(region = region,
+               projection = projection,
+               rose = "g0/0+w2.5c+jCM+l",
+               frame = True)
+
+    # Fancy, 2.5 cm wide rose of level 1 with only one label indicating the North
+    # direction. Colors of the rose and labels are defined via
+    # MAP_DEFAULT_PEN, MAP_TICK_PEN_PRIMARY and FONT_TITLE, respectively.
+    with fig.set_panel(panel=5):
+
+        with pygmt.config(MAP_DEFAULT_PEN="default,pink",
+                          MAP_TICK_PEN_PRIMARY="thick,red3",
+                          FONT_TITLE="8p,Bookman-Light,red3"):
+        
+          fig.basemap(region = region,
+           projection = projection,
+           rose = "g0/0+w2.5c+f1+jCM+l,,,N",
+           frame = True)
+
+    # Fancy, 2.5 cm wide rose of level 2 with two labels indicating the West and
+    # East directions. Colors of the rose and labels are defined via
+    # MAP_DEFAULT_PEN, MAP_TICK_PEN_PRIMARY and FONT_TITLE, respectively
+    with fig.set_panel(panel=6):
+
+        with pygmt.config(MAP_DEFAULT_PEN="default,lightorange",
+                          MAP_TICK_PEN_PRIMARY="thick,darkorange",
+                          FONT_TITLE="8p,Bookman-Light,darkorange"):
+        
+          fig.basemap(region = region,
+           projection = projection,
+           rose = "g0/0+w2.5c+f2+jCM+lW,E,,",
+           frame = True)        
+
+    # Fancy, 2.5 cm wide rose of level 3 with two labels indicating the North and
+    # South directions. Colors of the rose and labels are defined via
+    # MAP_DEFAULT_PEN, MAP_TICK_PEN_PRIMARY and FONT_TITLE, respectively
+    with fig.set_panel(panel=7):
+
+        with pygmt.config(MAP_DEFAULT_PEN="default,Dodgerblue4",
+                          MAP_TICK_PEN_PRIMARY="thick,Dodgerblue",   
+                          FONT_TITLE="8p,AvantGarde-Demi,Dodgerblue4"):
+
+          fig.basemap(region = region,
+           projection = projection,
+           rose = "g0/0+w2.5c+f3+l,,South,North+jCM",
+           frame = True)     
+
+fig.show()

From 929b66919e2e571976eed1685e99c3a7b4fad565 Mon Sep 17 00:00:00 2001
From: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
Date: Wed, 23 Jul 2025 17:23:29 +0200
Subject: [PATCH 2/7] rm tws

---
 examples/gallery/embellishments/map_roses.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/gallery/embellishments/map_roses.py b/examples/gallery/embellishments/map_roses.py
index 0c457da1c15..6ac0f0380cf 100644
--- a/examples/gallery/embellishments/map_roses.py
+++ b/examples/gallery/embellishments/map_roses.py
@@ -129,7 +129,7 @@
           fig.basemap(region = region,
            projection = projection,
            rose = "g0/0+w2.5c+f2+jCM+lW,E,,",
-           frame = True)        
+           frame = True)
 
     # Fancy, 2.5 cm wide rose of level 3 with two labels indicating the North and
     # South directions. Colors of the rose and labels are defined via
@@ -143,6 +143,6 @@
           fig.basemap(region = region,
            projection = projection,
            rose = "g0/0+w2.5c+f3+l,,South,North+jCM",
-           frame = True)     
+           frame = True)
 
 fig.show()

From 5dac68f46bae1369281e620aef953c6181e244f8 Mon Sep 17 00:00:00 2001
From: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
Date: Thu, 24 Jul 2025 08:31:23 +0200
Subject: [PATCH 3/7] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>
---
 examples/gallery/embellishments/map_roses.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/examples/gallery/embellishments/map_roses.py b/examples/gallery/embellishments/map_roses.py
index 6ac0f0380cf..99d6e52ff53 100644
--- a/examples/gallery/embellishments/map_roses.py
+++ b/examples/gallery/embellishments/map_roses.py
@@ -43,6 +43,7 @@
 and :gmt-term:`MAP_TICK_PEN_PRIMARY` via :func:`pygmt.config`. Customizing
 label font and color can be done via :gmt-term:`FONT_TITLE`.
 """
+import pygmt
 
 fig = pygmt.Figure()
 

From d1f7d9e98643ad4cbdf685477d046c86f1230afa Mon Sep 17 00:00:00 2001
From: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
Date: Mon, 28 Jul 2025 11:40:25 +0200
Subject: [PATCH 4/7] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>
---
 examples/gallery/embellishments/map_roses.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/gallery/embellishments/map_roses.py b/examples/gallery/embellishments/map_roses.py
index 99d6e52ff53..fa7a0ff6513 100644
--- a/examples/gallery/embellishments/map_roses.py
+++ b/examples/gallery/embellishments/map_roses.py
@@ -21,7 +21,7 @@
 - width: **+w**: Set the width of the rose in plot coordinates (append
   **i** (inch), **cm** (centimeters), or **p** (points).
 
-- fanciness: **+f**[level]: Get a “fancy” rose, and optionally specify the
+- fanciness: **+f** \[level]: Get a “fancy” rose, and optionally specify the
   level of fanciness. Level 1 draws the two principal E-W, N-S orientations,
   2 adds the two intermediate NW-SE and NE-SW orientations, while 3 adds
   the eight minor orientations WNW-ESE, NNW-SSE, NNE-SSW, and ENE-WSW

From b682ff67d24b1480c4e09fdeb3ea2d92467d01b4 Mon Sep 17 00:00:00 2001
From: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
Date: Mon, 28 Jul 2025 11:40:42 +0200
Subject: [PATCH 5/7] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>
---
 examples/gallery/embellishments/map_roses.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/gallery/embellishments/map_roses.py b/examples/gallery/embellishments/map_roses.py
index fa7a0ff6513..750df95238c 100644
--- a/examples/gallery/embellishments/map_roses.py
+++ b/examples/gallery/embellishments/map_roses.py
@@ -24,14 +24,14 @@
 - fanciness: **+f** \[level]: Get a “fancy” rose, and optionally specify the
   level of fanciness. Level 1 draws the two principal E-W, N-S orientations,
   2 adds the two intermediate NW-SE and NE-SW orientations, while 3 adds
-  the eight minor orientations WNW-ESE, NNW-SSE, NNE-SSW, and ENE-WSW
-  [default is 1].
+  the four minor orientations WNW-ESE, NNW-SSE, NNE-SSW, and ENE-WSW
+  [Default is 1].
 
 - justify: **+j**: 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).
 
-- label: **+l**[w,e,s,n]: Label the cardinal points W,E,S,N. Optionally,
+- label: **+l**\[w,e,s,n]: Label the cardinal points W,E,S,N. Optionally,
   append your own four comma-separated strings to override the default.
   Skip a specific label by leaving it blank.
 

From 0776071a7f2d3088f629a59d39133e4a36cc3bac Mon Sep 17 00:00:00 2001
From: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
Date: Mon, 28 Jul 2025 11:42:02 +0200
Subject: [PATCH 6/7] Apply suggestions from code review

---
 examples/gallery/embellishments/map_roses.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/gallery/embellishments/map_roses.py b/examples/gallery/embellishments/map_roses.py
index 750df95238c..5f6bbf60a23 100644
--- a/examples/gallery/embellishments/map_roses.py
+++ b/examples/gallery/embellishments/map_roses.py
@@ -21,7 +21,7 @@
 - width: **+w**: Set the width of the rose in plot coordinates (append
   **i** (inch), **cm** (centimeters), or **p** (points).
 
-- fanciness: **+f** \[level]: Get a “fancy” rose, and optionally specify the
+- fanciness: **+f** \[level]: Get a "fancy" rose, and optionally specify the
   level of fanciness. Level 1 draws the two principal E-W, N-S orientations,
   2 adds the two intermediate NW-SE and NE-SW orientations, while 3 adds
   the four minor orientations WNW-ESE, NNW-SSE, NNE-SSW, and ENE-WSW

From c23f5c63b875b1793e71cea3766b83a4cbc307a4 Mon Sep 17 00:00:00 2001
From: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
Date: Mon, 28 Jul 2025 16:26:44 +0200
Subject: [PATCH 7/7] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>
---
 examples/gallery/embellishments/map_roses.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/examples/gallery/embellishments/map_roses.py b/examples/gallery/embellishments/map_roses.py
index 5f6bbf60a23..a98bd1c9eed 100644
--- a/examples/gallery/embellishments/map_roses.py
+++ b/examples/gallery/embellishments/map_roses.py
@@ -18,24 +18,24 @@
    - **n**: Give normalized bounding box coordinates as *nx*\/\ *ny*.
    - **x**: Give plot coordinates as *x*\/\ *y*.
 
-- width: **+w**: Set the width of the rose in plot coordinates (append
+- width: **+w**. Set the width of the rose in plot coordinates (append
   **i** (inch), **cm** (centimeters), or **p** (points).
 
-- fanciness: **+f** \[level]: Get a "fancy" rose, and optionally specify the
+- fanciness: **+f**\[level]. Get a "fancy" rose, and optionally specify the
   level of fanciness. Level 1 draws the two principal E-W, N-S orientations,
   2 adds the two intermediate NW-SE and NE-SW orientations, while 3 adds
   the four minor orientations WNW-ESE, NNW-SSE, NNE-SSW, and ENE-WSW
   [Default is 1].
 
-- justify: **+j**: Set the anchor point. Specify a two-character (order
+- justify: **+j**. 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).
 
-- label: **+l**\[w,e,s,n]: Label the cardinal points W,E,S,N. Optionally,
+- label: **+l**\[w,e,s,n]. Label the cardinal points W,E,S,N. Optionally,
   append your own four comma-separated strings to override the default.
   Skip a specific label by leaving it blank.
 
-- offset: **+o**\ *offset* or **+o**\ *xoffset*/\ *yoffset*: Give either a
+- offset: **+o**\ *offset* or **+o**\ *xoffset*/\ *yoffset*. Give either a
   common shift or individual shifts in x- (longitude) and y- (latitude)
   directions.