Merge branch 'main' into copilot/update-figure-map-usage

Author: seisman

doc/api/index.rst

@@ -34,6 +34,7 @@ Plotting figure elements
     Figure.legend
     Figure.logo
     Figure.magnetic_rose
+    Figure.paragraph
     Figure.scalebar
     Figure.solar
     Figure.text

examples/gallery/embellishments/directional_roses.py

@@ -0,0 +1,109 @@
+"""
+Directional map rose
+====================
+
+The :meth:`pygmt.Figure.directional_rose` method allows to add directional roses on
+maps. Using the method without any arguments will plot a rose at the bottom left corner,
+but this example will focus on customizing its position and appearance.
+
+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
+from pygmt.params import Position
+
+fig = pygmt.Figure()
+
+y0 = 20
+y1 = -5
+width = "1.5c"
+
+fig.basemap(region=[-5, 80, -17, 32], projection="M10c", frame=True)
+
+# Plain rose of 1.5 cm width showing an arrow towards North, a cross indicating the
+# cardinal directions, and a label for the North direction
+fig.directional_rose(
+    width=width, labels=True, position=Position((0, y0), cstype="mapcoords")
+)
+
+# Fancy, 1.5 cm wide rose of level 1 and labels indicating the different directions
+fig.directional_rose(
+    width=width,
+    labels=True,
+    position=Position((20, y0), cstype="mapcoords"),
+    fancy=True,
+)
+
+# Fancy, 1.5 cm wide rose of level 2 and labels indicating the different directions
+fig.directional_rose(
+    width=width,
+    labels=True,
+    position=Position((45, y0), cstype="mapcoords"),
+    fancy=2,
+)
+
+# Fancy, 1.5 cm wide rose of level 3 and labels indicating the different directions
+fig.directional_rose(
+    width=width,
+    labels=True,
+    position=Position((70, y0), cstype="mapcoords"),
+    fancy=3,
+)
+
+# Plain rose of 1.5 cm width showing an arrow towards North, a cross indicating the
+# cardinal directions, and a label for the North direction. Colors of the rose and
+# labels are defined via MAP_TICK_PEN_PRIMARY and FONT_TITLE, respectively
+with pygmt.config(MAP_TICK_PEN_PRIMARY="purple", FONT_TITLE="8p,darkmagenta"):
+    fig.directional_rose(
+        width=width,
+        labels=True,
+        position=Position((0, y1), cstype="mapcoords"),
+    )
+
+# Fancy, 1.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 pygmt.config(
+    MAP_DEFAULT_PEN="default,pink",
+    MAP_TICK_PEN_PRIMARY="red3",
+    FONT_TITLE="8p,Bookman-Light,red3",
+):
+    fig.directional_rose(
+        width=width,
+        labels=["", "", "", "N"],
+        position=Position((20, y1), cstype="mapcoords"),
+        fancy=True,
+    )
+
+# Fancy, 1.5 cm wide rose of level 2 with two labels indicating the West and East
+# directions
+with pygmt.config(
+    MAP_DEFAULT_PEN="default,lightorange",
+    MAP_TICK_PEN_PRIMARY="darkorange",
+    FONT_TITLE="8p,Bookman-Light,darkorange",
+):
+    fig.directional_rose(
+        width=width,
+        labels=["W", "E", "", ""],
+        position=Position((45, y1), cstype="mapcoords"),
+        fancy=2,
+    )
+
+# Fancy, 1.5 cm wide rose of level 3 with two labels indicating the North and South
+# directions
+with pygmt.config(
+    MAP_DEFAULT_PEN="default,Dodgerblue4",
+    MAP_TICK_PEN_PRIMARY="Dodgerblue",
+    FONT_TITLE="8p,AvantGarde-Demi,Dodgerblue4",
+):
+    fig.directional_rose(
+        width=width,
+        labels=["", "", "South", "North"],
+        position=Position((70, y1), cstype="mapcoords"),
+        fancy=3,
+    )
+
+fig.show()

examples/gallery/embellishments/timestamp.py

@@ -12,6 +12,7 @@
 import os
 
 import pygmt
+from pygmt.params import Axis
 
 fig = pygmt.Figure()
 fig.basemap(region=[20, 30, -10, 10], projection="X10c/5c", frame=True)
@@ -25,7 +26,13 @@
 os.environ["TZ"] = "Pacific/Honolulu"  # optionally set the time zone
 
 fig = pygmt.Figure()
-fig.coast(region="d", projection="H10c", land="black", water="cornsilk", frame="afg")
+fig.coast(
+    region="d",
+    projection="H10c",
+    land="black",
+    water="cornsilk",
+    frame=Axis(annot=True, tick=True, grid=True),
+)
 fig.timestamp(
     label="Powered by PyGMT",
     justify="TL",

examples/gallery/histograms/histogram.py

@@ -11,6 +11,7 @@
 # %%
 import numpy as np
 import pygmt
+from pygmt.params import Axis, Frame
 
 # Generate random elevation data from a normal distribution
 rng = np.random.default_rng(seed=100)
@@ -23,9 +24,15 @@
 
 fig.histogram(
     data=data,
-    # Define the frame, add a title, and set the background color to
-    # "lightgray". Add labels to the x-axis and y-axis
-    frame=["WSne+tHistogram+glightgray", "x+lElevation (m)", "y+lCounts"],
+    # Define the frame, add a title, and set the background color to "lightgray".
+    # Add labels to the x-axis and y-axis
+    frame=Frame(
+        axes="WSne",
+        title="Histogram",
+        fill="lightgray",
+        xaxis=Axis(label="Elevation (m)"),
+        yaxis=Axis(label="Counts"),
+    ),
     # Generate evenly spaced bins by increments of 5
     series=5,
     # Use "red3" as color fill for the bars

examples/gallery/histograms/rose.py

@@ -8,6 +8,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Axis, Frame
 
 # Load sample compilation of fracture lengths and azimuth as
 # hypothetically digitized from geological maps
@@ -34,11 +35,9 @@
     norm=True,
     # use red3 as color fill for the sectors
     fill="red3",
-    # define the frame with ticks and gridlines every 0.2
-    # length unit in radial direction and every 30 degrees
-    # in azimuthal direction, set background color to
-    # lightgray
-    frame=["x0.2g0.2", "y30g30", "+glightgray"],
+    # define the frame with gridlines every 0.2 length unit in radial direction
+    # and every 30 degrees in azimuthal direction, set background color to lightgray
+    frame=Frame(xaxis=Axis(grid=0.2), yaxis=Axis(grid=30), fill="lightgray"),
     # use a pen size of 1p to draw the outlines
     pen="1p",
 )

examples/gallery/images/contours.py

@@ -23,6 +23,7 @@
 # %%
 import numpy as np
 import pygmt
+from pygmt.params import Axis
 
 # Build the contours underlying data with the function z = x^2 + y^2
 X, Y = np.meshgrid(np.linspace(-10, 10, 50), np.linspace(-10, 10, 50))
@@ -34,7 +35,7 @@
 fig.contour(
     region=[-10, 10, -10, 10],
     projection="X10c/10c",
-    frame="ag",
+    frame=Axis(annot=True, grid=True),
     pen="0.5p",
     # Pass the data as 3 1-D data columns
     x=x,

examples/gallery/images/cross_section.py

@@ -14,7 +14,7 @@
 
 # %%
 import pygmt
-from pygmt.params import Box, Position
+from pygmt.params import Axis, Box, Position
 
 # Define region of study area
 # lon_min, lon_max, lat_min, lat_max in degrees East and North
@@ -30,7 +30,7 @@
 # Bottom: Map of elevation in study area
 
 # Set up basic map using a Mercator projection with a width of 12 centimeters
-fig.basemap(region=region_map, projection="M12c", frame="af")
+fig.basemap(region=region_map, projection="M12c", frame=Axis(annot=True, tick=True))
 
 # Download grid for Earth relief with a resolution of 10 arc-minutes and gridline
 # registration [Default]

examples/gallery/lines/line_segment_ends.py

@@ -11,6 +11,7 @@
 # %%
 import numpy as np
 import pygmt
+from pygmt.params import Frame
 
 # Set up dictionary for colors
 dict_col = {
@@ -31,7 +32,7 @@
 x = np.array([30, 170])
 y = np.array([70, 70])
 
-fig.basemap(region=[0, 260, 0, 100], projection="x1p", frame="rltb")
+fig.basemap(region=[0, 260, 0, 100], projection="x1p", frame=Frame(axes="rltb"))
 
 for line_cap in ["butt", "round", "square"]:
     # Change GMT default locally
@@ -58,7 +59,7 @@
 x = np.array([5, 95, 65])
 y = np.array([10, 70, 10])
 
-fig.basemap(region=[0, 260, 0, 100], projection="x1p", frame="rltb")
+fig.basemap(region=[0, 260, 0, 100], projection="x1p", frame=Frame(axes="rltb"))
 
 for line_join in ["bevel", "round", "miter"]:
     with pygmt.config(PS_LINE_JOIN=line_join, PS_MITER_LIMIT=1):

examples/gallery/maps/borders.py

@@ -18,11 +18,16 @@
 
 # %%
 import pygmt
+from pygmt.params import Axis
 
 fig = pygmt.Figure()
 # Make a Sinusoidal projection map of the Americas with automatic annotations,
 # ticks and gridlines
-fig.basemap(region=[-150, -30, -60, 60], projection="I-90/15c", frame="afg")
+fig.basemap(
+    region=[-150, -30, -60, 60],
+    projection="I-90/15c",
+    frame=Axis(annot=True, tick=True, grid=True),
+)
 # Plot each level of the boundaries dataset with a different color.
 fig.coast(borders=["1/0.5p,black", "2/0.5p,red", "3/0.5p,blue"], land="gray")
 fig.show()

examples/gallery/maps/country_polygons.py

@@ -12,6 +12,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Axis
 
 fig = pygmt.Figure()
 
@@ -21,7 +22,7 @@
     projection="A10/52/25/6c",
     land="gray",
     water="white",
-    frame="afg",
+    frame=Axis(annot=True, tick=True, grid=True),
     dcw=[
         # Great Britain (country code) with seagreen land
         "GB+gseagreen",
@@ -54,7 +55,7 @@
     projection="H10c",
     land="gray",
     water="white",
-    frame="afg",
+    frame=Axis(annot=True, tick=True, grid=True),
     dcw=[
         # Europe
         "=EU+gseagreen",