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

Author: yvonnefroehlich

examples/gallery/histograms/scatter_and_histograms.py

@@ -11,6 +11,7 @@
 # %%
 import numpy as np
 import pygmt
+from pygmt.params import Axis, Frame
 
 # Generate random x-, y-coordinates from a standard normal distribution.
 # x-values are centered on 0 with a standard deviation of 1, and y-values are centered
@@ -35,7 +36,7 @@
 fig.basemap(
     region=[xmin, xmax, ymin, ymax],
     projection=f"X{width}/{height}",
-    frame=["WSrt", "af"],
+    frame=Frame(axes="WSrt", axis=Axis(annot=True, tick=True)),
 )
 
 # Plot data points as circles with a diameter of 0.15 centimeters and set transparency
@@ -46,7 +47,11 @@
 with fig.shift_origin(yshift=height + 0.25):
     fig.histogram(
         projection=f"X{width}/3",
-        frame=["Wsrt", "xf", "yaf+lCounts"],
+        frame=Frame(
+            axes="Wsrt",
+            xaxis=Axis(tick=True),
+            yaxis=Axis(annot=True, tick=True, label="Counts"),
+        ),
         # Give the same value for ymin and ymax to have them calculated automatically.
         region=[xmin, xmax, 0, 0],
         data=x,
@@ -63,7 +68,11 @@
         horizontal=True,
         projection=f"X3/{height}",
         # Note that the x- and y-axes are flipped, with the y-axis plotted horizontally.
-        frame=["wSrt", "xf", "yaf+lCounts"],
+        frame=Frame(
+            axes="wSrt",
+            xaxis=Axis(tick=True),
+            yaxis=Axis(annot=True, tick=True, label="Counts"),
+        ),
         region=[ymin, ymax, 0, 0],
         data=y,
         fill=fill,

pygmt/params/frame.py

@@ -79,11 +79,13 @@ class _Axes(BaseParam):
 
     axes: str | None = None
     title: str | None = None
+    fill: str | None = None
 
     @property
     def _aliases(self):
         return [
             Alias(self.axes, name="axes"),
+            Alias(self.fill, name="fill", prefix="+g"),
             Alias(self.title, name="title", prefix="+t"),
         ]
 
@@ -173,6 +175,10 @@ class Frame(BaseParam):
     #: The title string centered above the plot frame [Default is no title].
     title: str | None = None
 
+    #: Fill for the interior of the frame with a color or a pattern [Default is no
+    #: fill].
+    fill: str | None = None
+
     #: Specify the attributes for axes by an :class:`Axis` object.
     #:
     #: The attributes for x and y axes can be specified in two ways: (1) specifying the
@@ -209,7 +215,7 @@ def _validate(self):
     def _aliases(self):
         # _Axes() maps to an empty string, which becomes '-B' without arguments and is
         # invalid when combined with individual axis settings (e.g., '-B -Bxaf -Byaf').
-        frame_settings = _Axes(axes=self.axes, title=self.title)
+        frame_settings = _Axes(axes=self.axes, title=self.title, fill=self.fill)
         return [
             Alias(frame_settings) if str(frame_settings) else Alias(None),
             Alias(self.axis, name="axis"),

pygmt/src/colorbar.py

@@ -210,6 +210,26 @@ def _alias_option_D(  # noqa: N802, PLR0913
     ]
 
 
+def _alias_option_N(dpi=None):  # noqa: N802
+    """
+    Return an Alias object for the colorbar encoding setting.
+
+    The ``dpi`` parameter controls how the colorbar is encoded graphically. Passing
+    ``0`` preferentially draws color rectangles. Any positive integer is passed through
+    as the rasterization resolution.
+
+    Examples
+    --------
+    >>> def parse(**kwargs):
+    ...     return AliasSystem(N=_alias_option_N(**kwargs)).get("N")
+    >>> parse(dpi=300)
+    '300'
+    >>> parse(dpi=0)
+    'p'
+    """
+    return Alias("p" if dpi == 0 else dpi, name="dpi")
+
+
 @fmt_docstring
 @use_alias(C="cmap", L="equalsize", Z="zfile")
 def colorbar(  # noqa: PLR0913
@@ -240,6 +260,7 @@ def colorbar(  # noqa: PLR0913
     log: bool = False,
     scale: float | None = None,
     monochrome: bool = False,
+    dpi: int | None = None,
     projection: str | None = None,
     region: Sequence[float | str] | str | None = None,
     frame: str | Sequence[str] | Literal["none"] | bool = False,
@@ -280,6 +301,7 @@ def colorbar(  # noqa: PLR0913
        - I = shading
        - J = projection
        - M = monochrome
+       - N = dpi
        - Q = log
        - R = region
        - V = verbose
@@ -414,6 +436,17 @@ def colorbar(  # noqa: PLR0913
         requested colorbar length.
     monochrome
         Force a monochrome graybar using the (television) YIQ transformation.
+    dpi
+        Control how the color scale should be encoded graphically.
+
+        - Use a positive integer to draw the color scale as image and set the effective
+          dots-per-inch for rasterization of color scales, which is useful for
+          continuous colormaps.
+        - Use ``dpi=0`` to draw color rectangles, which is useful for discrete
+          colormaps.
+
+        If not specified, GMT uses its default encoding behavior, and the default dpi
+        is 600 if the colorbar is drawn as image.
     $projection
     $region
     $verbose
@@ -472,6 +505,7 @@ def colorbar(  # noqa: PLR0913
         G=Alias(truncate, name="truncate", sep="/", size=2),
         I=Alias(shading, name="shading", sep="/", size=2),
         M=Alias(monochrome, name="monochrome"),
+        N=_alias_option_N(dpi=dpi),
         Q=Alias(log, name="log"),
         W=Alias(scale, name="scale"),
     ).add_common(

pygmt/tests/test_params_frame.py

@@ -23,6 +23,9 @@ def test_params_frame_only():
     assert str(Frame("WSen")) == "WSen"
     assert str(Frame(axes="WSEN", title="My Title")) == "WSEN+tMy Title"
 
+    frame = str(Frame(axes="WSEN", title="My Title", fill="red"))
+    assert frame == "WSEN+gred+tMy Title"
+
 
 def test_params_frame_axis():
     """

pygmt/tests/test_plot.py

@@ -12,6 +12,7 @@
 from pygmt import Figure, which
 from pygmt.exceptions import GMTInvalidInput, GMTParameterError, GMTTypeError
 from pygmt.helpers import GMTTempFile
+from pygmt.params import Axis, Frame
 
 POINTS_DATA = Path(__file__).parent / "data" / "points.txt"
 
@@ -45,7 +46,7 @@ def test_plot_red_circles(data, region):
         projection="X10c",
         style="c0.2c",
         fill="red",
-        frame="afg",
+        frame=Axis(annot=True, tick=True, grid=True),
     )
     return fig
 
@@ -57,7 +58,11 @@ def test_plot_fail_no_data(data, region):
     fig = Figure()
     with pytest.raises(GMTInvalidInput):
         fig.plot(
-            region=region, projection="X10c", style="c0.2c", fill="red", frame="afg"
+            region=region,
+            projection="X10c",
+            style="c0.2c",
+            fill="red",
+            frame=Axis(annot=True, tick=True, grid=True),
         )
     with pytest.raises(GMTInvalidInput):
         fig.plot(
@@ -66,7 +71,7 @@ def test_plot_fail_no_data(data, region):
             projection="X10c",
             style="c0.2c",
             fill="red",
-            frame="afg",
+            frame=Axis(annot=True, tick=True, grid=True),
         )
     with pytest.raises(GMTInvalidInput):
         fig.plot(
@@ -75,7 +80,7 @@ def test_plot_fail_no_data(data, region):
             projection="X10c",
             style="c0.2c",
             fill="red",
-            frame="afg",
+            frame=Axis(annot=True, tick=True, grid=True),
         )
     # Should also fail if given too much data
     with pytest.raises(GMTParameterError):
@@ -87,7 +92,7 @@ def test_plot_fail_no_data(data, region):
             projection="X10c",
             style="c0.2c",
             fill="red",
-            frame="afg",
+            frame=Axis(annot=True, tick=True, grid=True),
         )
 
 
@@ -97,7 +102,12 @@ def test_plot_fail_1d_array_with_data(data, region):
     symbol are specified when data is given.
     """
     fig = Figure()
-    kwargs = {"data": data, "region": region, "projection": "X10c", "frame": "afg"}
+    kwargs = {
+        "data": data,
+        "region": region,
+        "projection": "X10c",
+        "frame": Frame(axis=Axis(annot=True, tick=True, grid=True)),
+    }
     with pytest.raises(GMTTypeError):
         fig.plot(style="c0.2c", fill=data[:, 2], **kwargs)
     with pytest.raises(GMTTypeError):
@@ -123,7 +133,7 @@ def test_plot_projection(data):
         projection="R270/10c",
         style="s0.2c",
         fill="green",
-        frame="ag",
+        frame=Axis(annot=True, grid=True),
     )
     return fig
 
@@ -142,7 +152,7 @@ def test_plot_colors(data, region):
         projection="X10c",
         style="c0.5c",
         cmap="cpt-city/cubhelix",
-        frame="af",
+        frame=Axis(annot=True, tick=True),
     )
     return fig
 
@@ -161,7 +171,7 @@ def test_plot_sizes(data, region):
         projection="X10c",
         style="cc",
         fill="blue",
-        frame="af",
+        frame=Axis(annot=True, tick=True),
     )
     return fig
 
@@ -181,7 +191,7 @@ def test_plot_colors_sizes(data, region):
         projection="X10c",
         style="cc",
         cmap="matlab/copper",
-        frame="af",
+        frame=Axis(annot=True, tick=True),
     )
     return fig
 
@@ -192,7 +202,12 @@ def test_plot_colors_sizes_proj(data, region):
     Plot the data using z as sizes and fills with a projection.
     """
     fig = Figure()
-    fig.coast(region=region, projection="M15c", frame="af", water="skyblue")
+    fig.coast(
+        region=region,
+        projection="M15c",
+        frame=Axis(annot=True, tick=True),
+        water="skyblue",
+    )
     fig.plot(
         x=data[:, 0],
         y=data[:, 1],
@@ -219,7 +234,7 @@ def test_plot_varying_intensity():
         y=y,
         region=[-1.1, 1.1, -0.5, 0.5],
         projection="X10c/2c",
-        frame=["S", "xaf+lIntensity"],
+        frame=Frame(axes="S", xaxis=Axis(annot=True, tick=True, label="Intensity")),
         style="c0.25c",
         fill="blue",
         intensity=intensity,
@@ -313,7 +328,7 @@ def test_plot_symbol():
         fill="blue",
         size=[0.1, 0.2, 0.3, 0.4],
         symbol=["c", "t", "i", "s"],
-        frame="af",
+        frame=Axis(annot=True, tick=True),
     )
     return fig
 
@@ -331,7 +346,7 @@ def test_plot_matrix(data, fill):
         projection="M15c",
         style="cc",
         fill=fill,
-        frame="a",
+        frame=Axis(annot=True),
         incols="0,1,2+s0.5",
     )
     return fig
@@ -349,7 +364,7 @@ def test_plot_matrix_color(data):
         projection="X10c",
         style="c0.5c",
         cmap="gmt/rainbow",
-        frame="a",
+        frame=Axis(annot=True),
     )
     return fig
 
@@ -391,7 +406,7 @@ def test_plot_vectors():
         projection="X10c",
         style="V0.2c+e+n",
         fill="black",
-        frame="af",
+        frame=Axis(annot=True, tick=True),
     )
     return fig
 
@@ -488,7 +503,11 @@ def test_plot_timedelta64():
     fig.basemap(
         projection="X8c/5c",
         region=[tmin, tmax, 0, 10],
-        frame=["WSne", "xaf+lForecast Days", "yaf+lRMSE"],
+        frame=Frame(
+            axes="WSne",
+            xaxis=Axis(annot=True, tick=True, label="Forecast Days"),
+            yaxis=Axis(annot=True, tick=True, label="RMSE"),
+        ),
     )
     fig.plot(
         x=np.arange(tmin, tmax),