Migrate list-based frame settings to Frame/Axis syntax across examples and docs (#4536)

Author: Copilot

examples/gallery/images/cross_section.py

@@ -14,7 +14,7 @@
 
 # %%
 import pygmt
-from pygmt.params import Axis, Box, Position
+from pygmt.params import Axis, Box, Frame, Position
 
 # Define region of study area
 # lon_min, lon_max, lat_min, lat_max in degrees East and North
@@ -120,6 +120,12 @@
 # Add map frame
 # Add annotations ("a") and ticks ("f") as well as labels ("+l") at the west or left
 # and south or bottom sides ("WSrt")
-fig.basemap(frame=["WSrt", "xa2f1+lDistance+u°", "ya4000+lElevation / m"])
+fig.basemap(
+    frame=Frame(
+        axes="WSrt",
+        xaxis=Axis(annot=2, tick=1, label="Distance", unit="°"),
+        yaxis=Axis(annot=4000, label="Elevation / m"),
+    )
+)
 
 fig.show()

examples/gallery/images/grdclip.py

@@ -10,7 +10,7 @@
 
 # %%
 import pygmt
-from pygmt.params.position import Position
+from pygmt.params import Axis, Frame, Position
 
 fig = pygmt.Figure()
 
@@ -24,7 +24,12 @@
 fig.basemap(
     region=region,
     projection="M12c",
-    frame=["WSne+toriginal grid", "xa5f1", "ya2f1"],
+    frame=Frame(
+        axes="WSne",
+        title="original grid",
+        xaxis=Axis(annot=5, tick=1),
+        yaxis=Axis(annot=2, tick=1),
+    ),
 )
 fig.grdimage(grid=grid, cmap="SCM/oleron")
 
@@ -39,7 +44,12 @@
 fig.basemap(
     region=region,
     projection="M12c",
-    frame=["wSne+tclipped grid", "xa5f1", "ya2f1"],
+    frame=Frame(
+        axes="wSne",
+        title="clipped grid",
+        xaxis=Axis(annot=5, tick=1),
+        yaxis=Axis(annot=2, tick=1),
+    ),
 )
 fig.grdimage(grid=grid)
 fig.colorbar(

examples/gallery/images/grdgradient.py

@@ -13,7 +13,7 @@
 
 # %%
 import pygmt
-from pygmt.params import Position
+from pygmt.params import Axis, Frame, Position
 
 # Define region of interest around Yosemite valley
 region = [-119.825, -119.4, 37.6, 37.825]
@@ -35,7 +35,12 @@
 fig.grdimage(
     grid=grid,
     projection="M12c",
-    frame=["WSrt+tOriginal Data Elevation Model", "xa0.1", "ya0.1"],
+    frame=Frame(
+        axes="WSrt",
+        title="Original Data Elevation Model",
+        xaxis=Axis(annot=0.1),
+        yaxis=Axis(annot=0.1),
+    ),
     cmap=True,
 )
 fig.colorbar(
@@ -57,7 +62,9 @@
 fig.grdimage(
     grid=dgrid,
     projection="M12c",
-    frame=["lSEt+tHillshade Map", "xa0.1", "ya0.1"],
+    frame=Frame(
+        axes="lSEt", title="Hillshade Map", xaxis=Axis(annot=0.1), yaxis=Axis(annot=0.1)
+    ),
     cmap=True,
 )
 

examples/gallery/images/grdgradient_shading.py

@@ -22,7 +22,7 @@
 
 # %%
 import pygmt
-from pygmt.params import Position
+from pygmt.params import Axis, Frame, Position
 
 # Load the 3 arc-minutes global relief grid in the target area around Caucasus
 grid = pygmt.datasets.load_earth_relief(resolution="03m", region=[35, 50, 35, 45])
@@ -58,10 +58,10 @@
                     grid=grid,
                     shading=shade,
                     projection="M?",
-                    frame=[
-                        "a4f2",
-                        f"+tazimuth={azi}, normalize={normalize}, amp={amp}",
-                    ],
+                    frame=Frame(
+                        title=f"azimuth={azi}, normalize={normalize}, amp={amp}",
+                        axis=Axis(annot=4, tick=2),
+                    ),
                     cmap=True,
                     panel=True,
                 )

examples/gallery/images/rgb_image.py

@@ -18,6 +18,7 @@
 # %%
 import pygmt
 import rioxarray
+from pygmt.params import Axis, Frame
 
 # %%
 # Read 3-band data from GeoTIFF into an xarray.DataArray object:
@@ -38,6 +39,10 @@
         grid=image,
         # Use a map scale where 1 cm on the map equals 1 km on the ground
         projection="x1:100000",
-        frame=[r"WSne+tL@!a¯hain@!a¯, Hawai`i on 9 Aug 2023", "af"],
+        frame=Frame(
+            axes="WSne",
+            title=r"L@!a¯hain@!a¯, Hawai`i on 9 Aug 2023",
+            axis=Axis(annot=True, tick=True),
+        ),
     )
 fig.show()

examples/gallery/lines/connection_lines.py

@@ -11,6 +11,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Axis, Frame
 
 # Set up same sample data
 x = [2.2, 3.3, -3.1, -3.7, -0.1]
@@ -21,7 +22,11 @@
 
 # -----------------------------------------------------------------------------
 # Left: record order
-fig.basemap(region=[-5, 5, -5, 5], projection="X6c", frame=["WSne", "af"])
+fig.basemap(
+    region=[-5, 5, -5, 5],
+    projection="X6c",
+    frame=Frame(axes="WSne", axis=Axis(annot=True, tick=True)),
+)
 
 # Connect data points based on the record order [Default connection=None]
 fig.plot(x=x, y=y, pen="1.5p,dodgerblue")
@@ -32,7 +37,11 @@
 
 # -----------------------------------------------------------------------------
 # Middle: network
-fig.basemap(region=[-5, 5, -5, 5], projection="X6c", frame=["wSne", "af"])
+fig.basemap(
+    region=[-5, 5, -5, 5],
+    projection="X6c",
+    frame=Frame(axes="wSne", axis=Axis(annot=True, tick=True)),
+)
 
 # Connect data points as network
 fig.plot(x=x, y=y, pen="1.5p,dodgerblue", connection="n")
@@ -43,7 +52,11 @@
 
 # -----------------------------------------------------------------------------
 # Right: reference point
-fig.basemap(region=[-5, 5, -5, 5], projection="X6c", frame=["wSne", "af"])
+fig.basemap(
+    region=[-5, 5, -5, 5],
+    projection="X6c",
+    frame=Frame(axes="wSne", axis=Axis(annot=True, tick=True)),
+)
 
 # Connect data points with the reference point (0,0)
 fig.plot(x=x, y=y, pen="1.5p,dodgerblue", connection="p0/0")

examples/gallery/lines/envelope.py

@@ -11,6 +11,7 @@
 # %%
 import pandas as pd
 import pygmt
+from pygmt.params import Axis, Frame
 
 # Define a pandas.DataFrame with columns for x and y as well as the lower and upper
 # deviations
@@ -41,7 +42,12 @@
 fig.basemap(
     region=[0, 10, -1.5, 1.5],
     projection="X10c",
-    frame=["WSne+tsymmetric deviations +d", "xa2f1", "ya1f0.1"],
+    frame=Frame(
+        axes="WSne",
+        title="symmetric deviations +d",
+        xaxis=Axis(annot=2, tick=1),
+        yaxis=Axis(annot=1, tick=0.1),
+    ),
 )
 
 # Plot a symmetrical envelope based on the deviations ("+d")
@@ -64,7 +70,12 @@
 fig.basemap(
     region=[0, 10, -1.5, 1.5],
     projection="X10c",
-    frame=["WSne+tasymmetric deviations +D", "xa2f1", "yf0.1"],
+    frame=Frame(
+        axes="WSne",
+        title="asymmetric deviations +D",
+        xaxis=Axis(annot=2, tick=1),
+        yaxis=Axis(tick=0.1),
+    ),
 )
 
 # Plot an asymmetrical envelope based on the deviations ("+D")
@@ -87,7 +98,12 @@
     region=[0, 10, -1.5, 1.5],
     projection="X10c",
     # Use "\\053" to handle "+b" as a string not as a modifier
-    frame=["wSnE+tbounds \\053b", "xa2f1", "ya1f0.1"],
+    frame=Frame(
+        axes="wSnE",
+        title="bounds \\053b",
+        xaxis=Axis(annot=2, tick=1),
+        yaxis=Axis(annot=1, tick=0.1),
+    ),
 )
 
 # Plot an envelope based on the bounds ("+b")

examples/gallery/lines/hlines_vlines.py

@@ -12,12 +12,14 @@
 # In Cartesian coordinate systems lines are plotted as straight lines.
 
 import pygmt
-from pygmt.params import Box, Position
+from pygmt.params import Axis, Box, Frame, Position
 
 fig = pygmt.Figure()
 
 fig.basemap(
-    region=[0, 10, 0, 10], projection="X10c/10c", frame=["+tCartesian hlines", "af"]
+    region=[0, 10, 0, 10],
+    projection="X10c/10c",
+    frame=Frame(title="Cartesian hlines", axis=Axis(annot=True, tick=True)),
 )
 
 # Add a horizontal line at y=9
@@ -37,7 +39,9 @@
 fig.shift_origin(xshift="w+2c")
 
 fig.basemap(
-    region=[0, 10, 0, 10], projection="X10c/10c", frame=["+tCartesian vlines", "af"]
+    region=[0, 10, 0, 10],
+    projection="X10c/10c",
+    frame=Frame(title="Cartesian vlines", axis=Axis(annot=True, tick=True)),
 )
 # Add a vertical line at x=1
 fig.vlines(x=1, pen="1.5p,red3", label="Line 1")
@@ -64,7 +68,11 @@
 
 fig = pygmt.Figure()
 
-fig.basemap(region="g", projection="R15c", frame=["+tGeographic hlines", "af"])
+fig.basemap(
+    region="g",
+    projection="R15c",
+    frame=Frame(title="Geographic hlines", axis=Axis(annot=True, tick=True)),
+)
 # Add a line at 70°N
 fig.hlines(y=70, pen="1.5p,red3", label="Line 1")
 # Add a line at 50°N with longitude limits at 20°E and 160°E
@@ -75,7 +83,11 @@
 
 fig.shift_origin(xshift="w+2c")
 
-fig.basemap(region="g", projection="R15c", frame=["+tGeographic vlines", "af"])
+fig.basemap(
+    region="g",
+    projection="R15c",
+    frame=Frame(title="Geographic vlines", axis=Axis(annot=True, tick=True)),
+)
 # Add a line at 70°E
 fig.vlines(x=70, pen="1.5p,red3", label="Line 1")
 # Add a line at 20°E with latitude limits at 50°S and 70°N
@@ -95,7 +107,11 @@
 
 fig = pygmt.Figure()
 
-fig.basemap(region=[0, 360, 0, 1], projection="P10c", frame=["+tPolar hlines", "af"])
+fig.basemap(
+    region=[0, 360, 0, 1],
+    projection="P10c",
+    frame=Frame(title="Polar hlines", axis=Axis(annot=True, tick=True)),
+)
 # Add a line along radius=0.8
 fig.hlines(y=0.8, pen="1.5p,red3", label="Line 1")
 # Add a line along radius=0.5 with azimuth limits at 30° and 160°
@@ -106,7 +122,11 @@
 
 fig.shift_origin(xshift="w+2c")
 
-fig.basemap(region=[0, 360, 0, 1], projection="P10c", frame=["+tPolar vlines", "af"])
+fig.basemap(
+    region=[0, 360, 0, 1],
+    projection="P10c",
+    frame=Frame(title="Polar vlines", axis=Axis(annot=True, tick=True)),
+)
 # Add a line along azimuth=120°
 fig.vlines(x=120, pen="1.5p,red3", label="Line 1")
 # Add a line along azimuth=190° with radius limits at 0.2 and 0.8

examples/gallery/lines/line_custom_cpt.py

@@ -15,12 +15,15 @@
 # %%
 import numpy as np
 import pygmt
+from pygmt.params import Axis, Frame
 
 # Create a list of values between 20 and 30 with 0.2 intervals
 x = np.arange(start=20, stop=30, step=0.2)
 
 fig = pygmt.Figure()
-fig.basemap(frame=["WSne", "af"], region=[20, 30, -10, 10])
+fig.basemap(
+    frame=Frame(axes="WSne", axis=Axis(annot=True, tick=True)), region=[20, 30, -10, 10]
+)
 
 # Create a custom CPT with the batlow CPT and 10 discrete z-values (colors),
 # use color_model="+c0-9" to write the color palette in categorical format and

examples/gallery/lines/wiggle.py

@@ -12,15 +12,19 @@
 # %%
 import numpy as np
 import pygmt
-from pygmt.params import Position
+from pygmt.params import Axis, Frame, Position
 
 # Create (x, y, z) triplets
 x = np.arange(-7, 7, 0.1)
 y = np.zeros(x.size)
 z = 50 * np.exp(-((x / 3) ** 2)) * np.cos(2 * np.pi * x)
 
 fig = pygmt.Figure()
-fig.basemap(region=[-8, 12, -1, 1], projection="X10c", frame=["Snlr", "xa2f1"])
+fig.basemap(
+    region=[-8, 12, -1, 1],
+    projection="X10c",
+    frame=Frame(axes="Snlr", xaxis=Axis(annot=2, tick=1)),
+)
 fig.wiggle(
     x=x,
     y=y,