Merge branch 'main' into rename-to-between_fill

Author: yvonnefroehlich

doc/api/index.rst

@@ -18,8 +18,8 @@ All plotting is handled through the :class:`pygmt.Figure` class and its methods.
 
     Figure
 
-Plotting map elements
-~~~~~~~~~~~~~~~~~~~~~
+Plotting figure elements
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autosummary::
     :toctree: generated
@@ -34,6 +34,7 @@ Plotting map elements
     Figure.legend
     Figure.logo
     Figure.magnetic_rose
+    Figure.paragraph
     Figure.scalebar
     Figure.solar
     Figure.text

examples/gallery/3d_plots/scatter3d.py

@@ -79,7 +79,7 @@
     fill=df.species.cat.codes.astype(int),
     # Use colormap created by makecpt
     cmap=True,
-    # Set map dimensions (xmin, xmax, ymin, ymax, zmin, zmax)
+    # Set plot dimensions (xmin, xmax, ymin, ymax, zmin, zmax)
     region=region,
     # Set frame parameters
     frame=Frame(

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/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, Frame, 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]
@@ -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")