DOC: Add gallery example to show usage of map roses

examples/gallery/embellishments/map_roses.py

@@ -0,0 +1,149 @@
+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 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,
+  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`.
+"""
+import pygmt
+
+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()