Merge branch 'main' into feature/paragraph

Author: seisman

.github/workflows/benchmarks.yml

@@ -84,7 +84,7 @@ jobs:
 
       # Run the benchmark tests
       - name: Run benchmarks
-        uses: CodSpeedHQ/action@281164b0f014a4e7badd2c02cecad9b595b70537 # v4.11.1
+        uses: CodSpeedHQ/action@d872884a306dd4853acf0f584f4b706cf0cc72a2 # v4.13.0
         with:
           mode: "instrumentation"
           # 'bash -el -c' is needed to use the custom shell.

.github/workflows/ci_tests.yaml

@@ -154,7 +154,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
         with:
           activate-environment: true
           python-version: ${{ matrix.python-version }}

.github/workflows/dvc-diff.yml

@@ -36,7 +36,7 @@ jobs:
       uses: iterative/setup-dvc@175771be1dc3d119268e00a896b52a4b77decb5e # v1.2.0
 
     - name: Setup continuous machine learning (CML)
-      uses: iterative/setup-cml@f714cd201b7183852dd6f94192b34e7618717560 # v2.0.0
+      uses: iterative/setup-cml@1b5ab8766e715e8f1aab96bbb1f4f2e3e1e8af45 # v3
 
     # Produce the markdown diff report, which should look like:
     # ## Summary of changed images

examples/gallery/3d_plots/grdview_surface.py

@@ -5,19 +5,17 @@
 The :meth:`pygmt.Figure.grdview()` method can plot 3-D surfaces with
 ``surftype="surface"``. Here, we supply the data as an :class:`xarray.DataArray` with
 the coordinate vectors ``x`` and ``y`` defined. Note that the ``perspective`` parameter
-here controls the azimuth and elevation angle of the view. We provide a list of two
-arguments to ``frame`` - the first argument specifies the :math:`x`- and :math:`y`-axes
-frame attributes and the second argument, prepended with ``"z"``, specifies the
-:math:`z`-axis frame attributes. Specifying the same scale for the ``projection`` and
-``zscale`` parameters ensures equal axis scaling. The ``shading`` parameter specifies
-illumination; here we choose an azimuth of 45° with ``shading="+a45"``.
+here controls the azimuth and elevation angle of the view. Specifying the same scale
+for the ``projection`` and ``zscale`` parameters ensures equal axis scaling. The
+``shading`` parameter specifies illumination; here we choose an azimuth of 45° with
+``shading="+a45"``.
 """
 
 # %%
 import numpy as np
 import pygmt
 import xarray as xr
-from pygmt.params import Position
+from pygmt.params import Axis, Frame, Position
 
 
 # Define an interesting function of two variables, see:
@@ -47,7 +45,10 @@ def ackley(x, y):
 fig.grdview(
     data,
     # Set annotations and gridlines in steps of five, and tick marks in steps of one
-    frame=["a5f1g5", "za5f1g5"],
+    frame=Frame(
+        axis=Axis(annot=5, tick=1, grid=5),  # x and y axes
+        zaxis=Axis(annot=5, tick=1, grid=5),
+    ),
     projection=f"x{SCALE}c",
     zscale=f"{SCALE}c",
     surftype="surface",

examples/gallery/3d_plots/scatter3d.py

@@ -9,14 +9,16 @@
 parameter has to include the :math:`x`, :math:`y`, :math:`z` axis limits in the
 form of (xmin, xmax, ymin, ymax, zmin, zmax), which can be done automatically
 using :func:`pygmt.info`. To plot the z-axis frame, set ``frame`` as a
-minimum to something like ``frame=["WsNeZ", "zaf"]``. Use ``perspective`` to
+minimum to something like ``Frame(axes="WsNeZ", zaxis=Axis(annot=True, tick=True))``.
+Use ``perspective`` to
 control the azimuth and elevation angle of the view, and ``zscale`` to adjust
 the vertical exaggeration factor.
 """
 
 # %%
 import pandas as pd
 import pygmt
+from pygmt.params import Axis, Frame
 
 # Load sample iris data
 df = pd.read_csv("https://github.com/mwaskom/seaborn-data/raw/master/iris.csv")
@@ -80,12 +82,13 @@
     # Set map dimensions (xmin, xmax, ymin, ymax, zmin, zmax)
     region=region,
     # Set frame parameters
-    frame=[
-        "WsNeZ3+tIris flower data set",  # z axis label positioned on 3rd corner, add title
-        "xafg+lPetal Width (cm)",
-        "yafg+lSepal Length (cm)",
-        "zafg+lPetal Length (cm)",
-    ],
+    frame=Frame(
+        axes="WsNeZ3",  # z axis label positioned on 3rd corner
+        title="Iris flower data set",
+        xaxis=Axis(annot=True, tick=True, grid=True, label="Petal Width (cm)"),
+        yaxis=Axis(annot=True, tick=True, grid=True, label="Sepal Length (cm)"),
+        zaxis=Axis(annot=True, tick=True, grid=True, label="Petal Length (cm)"),
+    ),
     # Set perspective to azimuth NorthWest (315°), at elevation 25°
     perspective=[315, 25],
     # Vertical exaggeration factor

examples/gallery/basemaps/double_y_axes.py

@@ -20,7 +20,7 @@ class can control which axes should be plotted and optionally show annotations,
 # %%
 import numpy as np
 import pygmt
-from pygmt.params import Position
+from pygmt.params import Axis, Frame, Position
 
 # Generate two sample Y-data from one common X-data
 x = np.linspace(1.0, 9.0, num=9)
@@ -33,7 +33,11 @@ class can control which axes should be plotted and optionally show annotations,
 # The bottom axis (S) is plotted with annotations and tick marks
 # The top axis (t) is plotted without annotations and tick marks
 # The left and right axes are not drawn
-fig.basemap(region=[0, 10, 0, 10], projection="X15c/15c", frame=["St", "xaf+lx"])
+fig.basemap(
+    region=[0, 10, 0, 10],
+    projection="X15c/15c",
+    frame=Frame(axes="St", xaxis=Axis(annot=True, tick=True, label="x")),
+)
 
 # Plot the Y-axis for y1-data
 # The left axis (W) is plotted with blue annotations, ticks, and label
@@ -43,7 +47,7 @@ class can control which axes should be plotted and optionally show annotations,
     FONT_ANNOT_PRIMARY="blue",
     FONT_LABEL="blue",
 ):
-    fig.basemap(frame=["W", "yaf+ly1"])
+    fig.basemap(frame=Frame(axes="W", yaxis=Axis(annot=True, tick=True, label="y1")))
 
 # Plot the line for y1-data
 fig.plot(x=x, y=y1, pen="1p,blue")
@@ -58,7 +62,10 @@ class can control which axes should be plotted and optionally show annotations,
     FONT_ANNOT_PRIMARY="red",
     FONT_LABEL="red",
 ):
-    fig.basemap(region=[0, 10, 100, 200], frame=["E", "yaf+ly2"])
+    fig.basemap(
+        region=[0, 10, 100, 200],
+        frame=Frame(axes="E", yaxis=Axis(annot=True, tick=True, label="y2")),
+    )
 # Plot the line for y2-data
 fig.plot(x=x, y=y2, pen="1p,red")
 # Plot points for y2-data

examples/gallery/embellishments/colorbar.py

@@ -13,10 +13,14 @@
 
 # %%
 import pygmt
-from pygmt.params import Position
+from pygmt.params import Axis, Frame, Position
 
 fig = pygmt.Figure()
-fig.basemap(region=[0, 3, 6, 9], projection="x3c", frame=["af", "WSne+tColorbars"])
+fig.basemap(
+    region=[0, 3, 6, 9],
+    projection="x3c",
+    frame=Frame(axes="WSne", title="Colorbars", axis=Axis(annot=True, tick=True)),
+)
 
 # ============
 # Create a colorbar designed for seismic tomography - roma

examples/gallery/embellishments/colorbars_multiple.py

@@ -10,6 +10,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Axis
 
 fig = pygmt.Figure()
 
@@ -28,15 +29,17 @@
         pygmt.makecpt(cmap="gmt/geo", series=[-8000, 8000])
         # "R?" means Winkel Tripel projection with map width automatically determined
         # from the subplot width.
-        fig.grdimage(grid=grid_globe, projection="R?", region="g", frame="a")
+        fig.basemap(projection="R?", region="g", frame=Axis(annot=True))
+        fig.grdimage(grid=grid_globe)
         fig.colorbar(annot=4000, tick=2000, label="Elevation", unit="m")
     # Activate the second panel so that the colormap created by the makecpt function is
     # a panel-level CPT
     with fig.set_panel(panel=1):
         pygmt.makecpt(cmap="gmt/globe", series=[-6000, 3000])
         # "M?" means Mercator projection with map width also automatically determined
         # from the subplot width.
-        fig.grdimage(grid=grid_subset, projection="M?", region=subset_region, frame="a")
+        fig.basemap(projection="M?", region=subset_region, frame=Axis(annot=True))
+        fig.grdimage(grid=grid_subset)
         fig.colorbar(annot=2000, tick=1000, label="Elevation", unit="m")
 
 fig.show()

examples/gallery/embellishments/inset.py

@@ -9,25 +9,28 @@
 
 # %%
 import pygmt
-from pygmt.params import Box, Position
+from pygmt.params import Axis, Box, Position
 
 fig = pygmt.Figure()
-# Create the primary figure, setting the region to Madagascar, the land color to
-# "brown", the water to "lightblue", the shorelines width to "thin", and adding a frame
-fig.coast(region="MG+r2", land="brown", water="lightblue", shorelines="thin", frame="a")
-# Create an inset, placing it in the Top Left (TL) corner with a width of 3.5 cm and
-# x- and y-offsets of 0.2 cm. The clearance is set to 0, and the border is "gold" with a
+# Create the primary figure, setting the region to Madagascar
+fig.basemap(region="MG+r2", projection="M12c", frame=Axis(annot=True))
+# Set the land color to "brown", the water color to "lightblue", and the shorelines
+# width to "thin"
+fig.coast(land="brown", water="lightblue", shorelines="thin")
+
+# Create an inset, placing it in the Top Left (TL) corner with a width of 3.5 cm and x-
+# and y-offsets of 0.2 cm. The clearance is set to 0, and the border is "gold" with a
 # pen thickness of 1.5 points.
 with fig.inset(
     position=Position("TL", offset=0.2),
     width=3.5,
     clearance=0,
     box=Box(pen="1.5p,gold"),
 ):
-    # Create a figure in the inset using coast. This example uses the azimuthal
-    # orthogonal projection centered at 47E, 20S. The land color is set to "gray" and
-    # Madagascar is highlighted in "red3".
-    fig.coast(
-        region="g", projection="G47/-20/?", land="gray", water="white", dcw="MG+gred3"
-    )
+    # Create a map within the inset. This example uses the azimuthal orthogonal
+    # projection centered at 47 E, 20 S. The question mark is required for the
+    # automatic size determination by PyGMT
+    fig.basemap(region="g", projection="G47/-20/?", frame=0)
+    # Madagascar is highlighted in "red3"
+    fig.coast(land="gray", water="white", dcw="MG+gred3")
 fig.show()

examples/gallery/embellishments/inset_rectangle_region.py

@@ -9,15 +9,19 @@
 
 # %%
 import pygmt
-from pygmt.params import Box, Position
+from pygmt.params import Axis, Box, Frame, Position
 
 # Set the region of the main figure
 region = [137.5, 141, 34, 37]
 
 fig = pygmt.Figure()
 # Plot the base map of the main figure. Universal Transverse Mercator (UTM) projection
 # is used and the UTM zone is set to be "54S".
-fig.basemap(region=region, projection="U54S/12c", frame=["WSne", "af"])
+fig.basemap(
+    region=region,
+    projection="U54S/12c",
+    frame=Frame(axes="WSne", axis=Axis(annot=True, tick=True)),
+)
 
 # Set the land color to "lightbrown", the water color to "azure1", the shoreline width
 # to "2p", and the area threshold to 1000 km^2 for the main figure.