Migrate frame settings to the Frame/Axis class [frame='WSen' or similar] (#4534)

Author: seisman

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/tutorials/advanced/grid_equalization.py

@@ -8,7 +8,7 @@
 
 # %%
 import pygmt
-from pygmt.params import Position
+from pygmt.params import Frame, Position
 
 # %%
 # Load sample data
@@ -43,7 +43,7 @@
 ):
     # Plot the original digital elevation model in the first panel
     with fig.set_panel(panel=0):
-        fig.grdimage(grid=grid, projection="M?", frame="WSne", cmap=True)
+        fig.grdimage(grid=grid, projection="M?", frame=Frame(axes="WSne"), cmap=True)
     # Plot a histogram showing the z-value distribution in the original digital
     # elevation model
     with fig.set_panel(panel=1):
@@ -117,7 +117,7 @@
 ):
     # Plot the grid with a linear distribution in the first panel
     with fig.set_panel(panel=0):
-        fig.grdimage(grid=linear, projection="M?", frame="WSne", cmap=True)
+        fig.grdimage(grid=linear, projection="M?", frame=Frame(axes="WSne"), cmap=True)
     # Plot a histogram showing the linear z-value distribution
     with fig.set_panel(panel=1):
         fig.histogram(
@@ -172,7 +172,7 @@
 ):
     # Plot the grid with a normal distribution in the first panel
     with fig.set_panel(panel=0):
-        fig.grdimage(grid=normal, projection="M?", frame="WSne", cmap=True)
+        fig.grdimage(grid=normal, projection="M?", frame=Frame(axes="WSne"), cmap=True)
     # Plot a histogram showing the normal z-value distribution
     with fig.set_panel(panel=1):
         fig.histogram(
@@ -241,7 +241,9 @@
 ):
     # Plot the grid with a quadratic distribution in the first panel
     with fig.set_panel(panel=0):
-        fig.grdimage(grid=quadratic, projection="M?", frame="WSne", cmap=True)
+        fig.grdimage(
+            grid=quadratic, projection="M?", frame=Frame(axes="WSne"), cmap=True
+        )
     # Plot a histogram showing the quadratic z-value distribution
     with fig.set_panel(panel=1):
         fig.histogram(

examples/tutorials/advanced/legends.py

@@ -10,7 +10,7 @@
 import io
 
 import pygmt
-from pygmt.params import Box, Position
+from pygmt.params import Box, Frame, Position
 
 # %%
 # Create an auto-legend
@@ -51,7 +51,7 @@
 # drawn by default if ``position`` is used
 
 fig = pygmt.Figure()
-fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame="rltb")
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=Frame(axes="rltb"))
 
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
 fig.plot(x=1, y=0, style="t0.3c", fill="pink", pen="black", label="pink triangle")
@@ -62,7 +62,7 @@
 fig.legend(position=Position("TL", offset=(0.3, 0.2)))
 
 fig.shift_origin(xshift="w+1c")
-fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame="rltb")
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=Frame(axes="rltb"))
 
 fig.plot(x=0, y=0, style="c0.25c", fill="orange", label="orange circle")
 fig.plot(x=1, y=0, style="t0.3c", fill="pink", pen="black", label="pink triangle")

examples/tutorials/advanced/subplots.py

@@ -20,6 +20,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Frame
 
 # %%
 # Let's start by initializing a :class:`pygmt.Figure` instance.
@@ -39,17 +40,22 @@
 # %%
 # .. code-block:: default
 #
-#     with fig.subplot(nrows=2, ncols=3, figsize=("15c", "6c"), frame="lrtb"):
+#     with fig.subplot(
+#         nrows=2,
+#         ncols=3,
+#         figsize=("15c", "6c"),
+#         frame=Frame(axes="lrtb"),
+#    ):
 #         ...
 
 # %%
 # will define our figure to have a 2 row and 3 column grid layout.
 # ``figsize=("15c", "6c")`` defines the overall size of the figure to be 15 cm wide by
-# 6 cm high. Using ``frame="lrtb"`` allows us to customize the map frame for all
-# subplots instead of setting them individually. The figure layout will look like the
-# following:
+# 6 cm high. Using ``frame=Frame(axes="lrtb")`` allows us to customize the map frame for
+# all subplots instead of setting them individually. The figure layout will look like
+# the following:
 
-with fig.subplot(nrows=2, ncols=3, figsize=("15c", "6c"), frame="lrtb"):
+with fig.subplot(nrows=2, ncols=3, figsize=("15c", "6c"), frame=Frame(axes="lrtb")):
     for i in range(2):  # row number starting from 0
         for j in range(3):  # column number starting from 0
             index = i * 3 + j  # index number starting from 0
@@ -169,7 +175,7 @@
     title="My Subplot Heading",
     sharex="b",  # shared x-axis on the bottom side
     sharey="l",  # shared y-axis on the left side
-    frame="WSrt",
+    frame=Frame(axes="WSrt"),
 ):
     fig.basemap(region=[0, 10, 0, 10], projection="X?", panel=True)
     fig.basemap(region=[0, 20, 0, 10], projection="X?", panel=True)

examples/tutorials/basics/text.py

@@ -10,6 +10,7 @@
 from pathlib import Path
 
 import pygmt
+from pygmt.params import Axis, Frame
 
 # %%
 # Adding a single text label
@@ -44,7 +45,7 @@
 
 # -----------------------------------------------------------------------------
 # Left: "font", "angle", and "offset" parameters
-fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame="rtlb")
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=Frame(axes="rtlb"))
 
 # Change font size, family/weight, color of the text
 fig.text(x=0, y=3, text="my text", font="12p,Helvetica-Bold,blue")
@@ -64,7 +65,7 @@
 
 # -----------------------------------------------------------------------------
 # Right: "justify" parameter
-fig.basemap(region=[-1, 1, -1, 1], projection="X5c", frame="rtlb")
+fig.basemap(region=[-1, 1, -1, 1], projection="X5c", frame=Frame(axes="rtlb"))
 
 # Plot markers for reference
 fig.plot(
@@ -103,7 +104,7 @@
 
 fig = pygmt.Figure()
 
-fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame="rtlb")
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=Frame(axes="rtlb"))
 
 # Add a box with a fill in green color
 fig.text(x=0, y=3, text="My text", fill="green")
@@ -156,7 +157,7 @@
 # and ``justify`` parameters can be provided. Here, we give a complete example.
 
 fig = pygmt.Figure()
-fig.basemap(region=[108, 121, -5, 8], projection="M10c", frame="a2f1")
+fig.basemap(region=[108, 121, -5, 8], projection="M10c", frame=Axis(annot=2, tick=1))
 fig.coast(land="darkgray", water="steelblue", shorelines="1/0.1p,gray30")
 
 # Create space-delimited file with region / sea names:

pygmt/tests/test_legend.py

@@ -9,6 +9,7 @@
 from pygmt import Figure
 from pygmt.exceptions import GMTParameterError, GMTTypeError
 from pygmt.helpers import GMTTempFile
+from pygmt.params import Axis
 
 
 @pytest.fixture(scope="module", name="legend_spec")
@@ -119,7 +120,7 @@ def test_legend_width_height():
 """
     )
     fig = Figure()
-    fig.basemap(projection="x1c", region=[0, 20, 0, 20], frame="g1")
+    fig.basemap(projection="x1c", region=[0, 20, 0, 20], frame=Axis(grid=1))
     # Default width and height
     fig.legend(spec, position="TL", box=True)
 

pygmt/tests/test_subplot.py

@@ -5,7 +5,7 @@
 import pytest
 from pygmt import Figure
 from pygmt.exceptions import GMTParameterError, GMTValueError
-from pygmt.params import Axis, Box, Position
+from pygmt.params import Axis, Box, Frame, Position
 
 
 @pytest.mark.benchmark
@@ -17,7 +17,7 @@ def test_subplot_basic_frame():
     """
     fig = Figure()
 
-    with fig.subplot(nrows=1, ncols=2, figsize=("6c", "3c"), frame="WSne"):
+    with fig.subplot(nrows=1, ncols=2, figsize=("6c", "3c"), frame=Frame(axes="WSne")):
         with fig.set_panel(panel="0,0"):
             fig.basemap(region=[0, 3, 0, 3], frame="+tplot0")
         with fig.set_panel(panel=[0, 1]):
@@ -57,8 +57,8 @@ def test_subplot_tag_margins_title():
         margins=["0.3c", "0.1c"],
         title="Subplot Title",
     ):
-        fig.basemap(region=[0, 1, 2, 3], frame="WSne", panel=[0, 0])
-        fig.basemap(region=[4, 5, 6, 7], frame="WSne", panel=[1, 0])
+        fig.basemap(region=[0, 1, 2, 3], frame=Frame(axes="WSne"), panel=[0, 0])
+        fig.basemap(region=[4, 5, 6, 7], frame=Frame(axes="WSne"), panel=[1, 0])
 
     return fig
 
@@ -75,7 +75,7 @@ def test_subplot_clearance_and_shared_xy_axis_layout():
         nrows=2,
         ncols=2,
         figsize=("5c", "5c"),
-        frame="WSrt",
+        frame=Frame(axes="WSrt"),
         clearance=["s0.2c", "n0.2c"],
         sharex="t",
         sharey=True,

pygmt/tests/test_timestamp.py

@@ -5,6 +5,7 @@
 import pytest
 from pygmt import Figure
 from pygmt.exceptions import GMTParameterError
+from pygmt.params import Axis
 
 
 @pytest.fixture(scope="module", name="faketime")
@@ -56,7 +57,7 @@ def test_timestamp_offset():
     Check if the "offset" parameter works.
     """
     fig = Figure()
-    fig.basemap(projection="X10c/5c", region=[0, 10, 0, 5], frame="g1")
+    fig.basemap(projection="X10c/5c", region=[0, 10, 0, 5], frame=Axis(grid=1))
     for offset in ["1c", "1c/2c", ("1c", "3c"), 4, (4, 1)]:
         fig.timestamp(offset=offset, timefmt=f"offset={offset}")
     return fig

pygmt/tests/test_vlines.py

@@ -5,6 +5,7 @@
 import pytest
 from pygmt import Figure
 from pygmt.exceptions import GMTValueError
+from pygmt.params import Axis
 
 
 @pytest.mark.mpl_image_compare
@@ -61,7 +62,11 @@ def test_vlines_geographic_global():
     Plot vertical lines in geographic coordinates.
     """
     fig = Figure()
-    fig.basemap(region=[-180, 180, -90, 90], projection="R15c", frame="a30g30")
+    fig.basemap(
+        region=[-180, 180, -90, 90],
+        projection="R15c",
+        frame=Axis(annot=30, grid=30),
+    )
     fig.vlines(30, pen="1p")
     fig.vlines(90, ymin=-60, pen="1p,blue")
     fig.vlines(-90, ymax=60, pen="1p,blue")