Merge branch 'main' into add-gallery-paragraph

Author: yvonnefroehlich

.github/workflows/benchmarks.yml

@@ -84,7 +84,7 @@ jobs:
 
       # Run the benchmark tests
       - name: Run benchmarks
-        uses: CodSpeedHQ/action@d872884a306dd4853acf0f584f4b706cf0cc72a2 # v4.13.0
+        uses: CodSpeedHQ/action@658a901452bb54c799643e060733b7afe9121b8d # v4.14.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@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
           activate-environment: true
           python-version: ${{ matrix.python-version }}

.github/workflows/dvc-diff.yml

@@ -37,6 +37,8 @@ jobs:
 
     - name: Setup continuous machine learning (CML)
       uses: iterative/setup-cml@1b5ab8766e715e8f1aab96bbb1f4f2e3e1e8af45 # v3
+      with:
+        vega: false
 
     # Produce the markdown diff report, which should look like:
     # ## Summary of changed images

examples/tutorials/basics/frames.py

@@ -2,114 +2,107 @@
 Frames, ticks, titles, and labels
 =================================
 
-Setting frame, ticks, title, etc., of the plot is handled by the ``frame``
-parameter that most plotting methods of the :class:`pygmt.Figure` class
-contain.
+Setting frame, ticks, titles, and labels is handled by the ``frame`` parameter that
+many plotting methods of the :class:`pygmt.Figure` class accept. This tutorial focuses
+on setting the ``frame`` parameter using the :class:`pygmt.params.Axis` and
+:class:`pygmt.params.Frame` classes.
 """
 
 # %%
 import pygmt
-from pygmt.params import Axis
+from pygmt.params import Axis, Frame
 
 # %%
 # Plot frame
 # ----------
 #
-# By default, PyGMT does not add a frame to your plot. For example, we can plot
-# the coastlines of the world with a Mercator projection:
+# By default, PyGMT does not add a frame to your plot. For example, we can plot the
+# coastlines of the world with a Mercator projection:
 
 fig = pygmt.Figure()
-fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M25c")
+fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M15c")
 fig.show()
 
 # %%
-# To add the default GMT frame style to the plot, use ``frame="f"`` in
-# :meth:`pygmt.Figure.basemap` or another plotting method (which has the
-# ``frame`` parameter, with the exception of :meth:`pygmt.Figure.colorbar`):
+# To add the default GMT frame style to the plot, use ``frame=True`` in
+# :meth:`pygmt.Figure.basemap` or another plotting method that accepts a ``frame``
+# parameter:
 
 fig = pygmt.Figure()
-fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M25c")
-fig.basemap(frame="f")
+fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M15c")
+fig.basemap(frame=True)
 fig.show()
 
 
 # %%
-# Ticks and grid lines
-# --------------------
+# Annotations, tick marks and grid lines
+# --------------------------------------
 #
-# The automatic frame (``frame=True`` or ``frame="af"``) adds the default GMT
-# frame style and automatically determines tick labels from the plot region.
-# In GMT the tick labels are called **a**\ nnotations.
-
-fig = pygmt.Figure()
-fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M25c")
-fig.basemap(frame="af")
-fig.show()
-
-# %%
-# Add automatic grid lines to the plot by passing ``g`` through the ``frame``
-# parameter:
+# The default frame style includes tick labels (called annotations in GMT) and tick
+# marks at intervals determined by GMT, but doesn't include grid lines. To control
+# the presence and intervals of annotations, tick marks, and grid lines, you can use the
+# :class:`pygmt.params.Axis` class. The ``annot``, ``tick``, and ``grid`` attributes of
+# :class:`pygmt.params.Axis` control the presence and intervals of annotations, tick
+# marks, and grid lines, respectively. Setting them to ``True`` adds them at intervals
+# determined by GMT:
 
 fig = pygmt.Figure()
-fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M25c")
-fig.basemap(frame=Axis(annot=True, grid=True))
+fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M15c")
+fig.basemap(frame=Axis(annot=True, tick=True, grid=True))
 fig.show()
 
 # %%
-# To adjust the step widths of annotations, frame, and grid lines we can
-# add the desired step widths after ``a``, ``f``, or ``g``. In the example
-# below, the step widths are set to 30°, 7.5°, and 15°, respectively.
+# To set specific intervals, pass values to ``annot``, ``tick``, and ``grid``. In the
+# example below, the annotation, tick, and gridline intervals are set to 30, 7.5, and
+# 15 degrees, respectively.
 
 fig = pygmt.Figure()
-fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M25c")
-fig.basemap(frame="a30f7.5g15")
+fig.coast(shorelines="1/0.5p", region=[-180, 180, -60, 60], projection="M15c")
+fig.basemap(frame=Axis(annot=30, tick=7.5, grid=15))
 fig.show()
 
-
 # %%
 # Title
 # -----
 #
-# The figure title can be set by passing **+t**\ *title* to the ``frame``
-# parameter of :meth:`pygmt.Figure.basemap`. Passing multiple arguments to
-# ``frame`` can be done by using a list, as shown in the example below.
+# The :class:`pygmt.params.Frame` class lets us configure frame-wide settings such as
+# titles. Combine it with an :class:`Axis` object to keep automatic annotations.
 
 fig = pygmt.Figure()
 # region="TT" specifies Trinidad and Tobago using the ISO country code
-fig.coast(shorelines="1/0.5p", region="TT", projection="M25c")
-fig.basemap(frame=["a", "+tTrinidad and Tobago"])
+fig.coast(shorelines="1/0.5p", region="TT", projection="M15c")
+fig.basemap(frame=Frame(title="Trinidad and Tobago", axis=Axis(annot=True)))
 fig.show()
 
 
 # %%
 # Axis labels
 # -----------
 #
-# Axis labels, in GMT simply called labels, can be set by passing
-# **x+l**\ *label* (or starting with **y** if
-# labeling the y-axis) to the ``frame`` parameter of
-# :meth:`pygmt.Figure.basemap`. The map boundaries (or plot axes) are named as
-# West/west/left (**W**, **w**, **l**), South/south/bottom
-# (**S**, **s**, **b**), North/north/top (**N**, **n**, **t**), and
-# East/east/right (**E**, **e**, **r**) sides of a figure. If an uppercase
-# letter (**W**, **S**, **N**, **E**) is passed, the axis is plotted with
-# tick marks and annotations. The lowercase version
-# (**w**, **s**, **n**, **e**) plots the axis only with tick marks.
-# To only plot the axis pass **l**, **b**, **t**, **r**. By default
-# (``frame=True`` or ``frame="af"``), the West and the South axes are
-# plotted with both tick marks and annotations.
+# Axis labels, in GMT simply called labels, can be set through the ``xaxis`` and
+# ``yaxis`` parameters of :class:`Frame`. The map boundaries (or plot axes) are named as
+# West/west/left (**W**, **w**, **l**), South/south/bottom (**S**, **s**, **b**),
+# North/north/top (**N**, **n**, **t**), and East/east/right (**E**, **e**, **r**) sides
+# of a figure. Uppercase letters (**W**, **S**, **N**, **E**) draw axes with annotations
+# and tick marks, lowercase letters (**w**, **s**, **n**, **e**) draw axes with tick
+# marks only, and **l**, **b**, **t**, **r** draw plain axis lines without ticks or
+# annotations. A frame like ``Frame(axes="WS")`` draws annotated west and south axes
+# only.
 #
-# The example below uses a Cartesian projection, as GMT does not allow
-# labels to be set for geographic maps.
+# The example below uses a Cartesian projection, as GMT does not allow labels to be set
+# for geographic maps.
 
 fig = pygmt.Figure()
 fig.basemap(
     region=[0, 10, 0, 20],
     projection="X10c/8c",
-    # Plot axis with tick marks, annotations, and labels on the
-    # West and South axes
+    # Plot axis with tick marks, annotations, and labels on the West and South axes.
     # Plot axis with tick marks on the north and east axes
-    frame=["WSne", "xaf+lx-axis", "yaf+ly-axis"],
+    frame=Frame(
+        axes="WSne",
+        xaxis=Axis(annot=True, tick=True, label="x-axis"),
+        yaxis=Axis(annot=True, tick=True, label="y-axis"),
+    ),
 )
 fig.show()
 

pygmt/figure.py

@@ -9,6 +9,40 @@
 from typing import Literal, overload
 
 from pygmt._typing import PathLike
+from pygmt.src.basemap import basemap as _basemap
+from pygmt.src.choropleth import choropleth as _choropleth
+from pygmt.src.coast import coast as _coast
+from pygmt.src.colorbar import colorbar as _colorbar
+from pygmt.src.contour import contour as _contour
+from pygmt.src.directional_rose import directional_rose as _directional_rose
+from pygmt.src.grdcontour import grdcontour as _grdcontour
+from pygmt.src.grdimage import grdimage as _grdimage
+from pygmt.src.grdview import grdview as _grdview
+from pygmt.src.histogram import histogram as _histogram
+from pygmt.src.hlines import hlines as _hlines
+from pygmt.src.image import image as _image
+from pygmt.src.inset import inset as _inset
+from pygmt.src.legend import legend as _legend
+from pygmt.src.logo import logo as _logo
+from pygmt.src.magnetic_rose import magnetic_rose as _magnetic_rose
+from pygmt.src.meca import meca as _meca
+from pygmt.src.paragraph import paragraph as _paragraph
+from pygmt.src.plot import plot as _plot
+from pygmt.src.plot3d import plot3d as _plot3d
+from pygmt.src.psconvert import psconvert as _psconvert
+from pygmt.src.rose import rose as _rose
+from pygmt.src.scalebar import scalebar as _scalebar
+from pygmt.src.shift_origin import shift_origin as _shift_origin
+from pygmt.src.solar import solar as _solar
+from pygmt.src.subplot import set_panel as _set_panel
+from pygmt.src.subplot import subplot as _subplot
+from pygmt.src.ternary import ternary as _ternary
+from pygmt.src.text import text as _text
+from pygmt.src.tilemap import tilemap as _tilemap
+from pygmt.src.timestamp import timestamp as _timestamp
+from pygmt.src.velo import velo as _velo
+from pygmt.src.vlines import vlines as _vlines
+from pygmt.src.wiggle import wiggle as _wiggle
 
 try:
     import IPython
@@ -408,42 +442,41 @@ def _repr_html_(self) -> str:
         html = '<img src="data:image/png;base64,{image}" width="{width}px">'
         return html.format(image=base64_png.decode("utf-8"), width=500)
 
-    from pygmt.src import (  # type: ignore[misc] # noqa: PLC0415
-        basemap,
-        choropleth,
-        coast,
-        colorbar,
-        contour,
-        directional_rose,
-        grdcontour,
-        grdimage,
-        grdview,
-        histogram,
-        hlines,
-        image,
-        inset,
-        legend,
-        logo,
-        magnetic_rose,
-        meca,
-        paragraph,
-        plot,
-        plot3d,
-        psconvert,
-        rose,
-        scalebar,
-        set_panel,
-        shift_origin,
-        solar,
-        subplot,
-        ternary,
-        text,
-        tilemap,
-        timestamp,
-        velo,
-        vlines,
-        wiggle,
-    )
+    # Attach plotting functions implemented in pygmt/src as Figure methods.
+    basemap = _basemap
+    choropleth = _choropleth
+    coast = _coast
+    colorbar = _colorbar
+    contour = _contour
+    directional_rose = _directional_rose
+    grdcontour = _grdcontour
+    grdimage = _grdimage
+    grdview = _grdview
+    histogram = _histogram
+    hlines = _hlines
+    image = _image
+    inset = _inset
+    legend = _legend
+    logo = _logo
+    magnetic_rose = _magnetic_rose
+    meca = _meca
+    paragraph = _paragraph
+    plot = _plot
+    plot3d = _plot3d
+    psconvert = _psconvert
+    rose = _rose
+    scalebar = _scalebar
+    set_panel = _set_panel
+    shift_origin = _shift_origin
+    solar = _solar
+    subplot = _subplot
+    ternary = _ternary
+    text = _text
+    tilemap = _tilemap
+    timestamp = _timestamp
+    velo = _velo
+    vlines = _vlines
+    wiggle = _wiggle
 
 
 def set_display(method: Literal["external", "notebook", "none", None] = None) -> None:

pygmt/helpers/decorators.py

@@ -91,11 +91,15 @@
             matching. This does not apply to headers or segment headers.""",
     "frame": r"""
         frame
-            Set frame and axes attributes for the plot. It can be a bool, a string, or
-            a list of strings. If ``frame=True``, frame will be drawn with the default
-            attributes. If ``frame="none"``, no frame will be drawn. A tutorial is
-            available at :doc:`frame and axes attributes </tutorials/basics/frames>`.
-            Full documentation is at :gmt-docs:`gmt.html#b-full`.""",
+            Set frame and axes attributes for the plot. It can be a bool, ``"none"``,
+            a :class:`pygmt.params.Frame` or :class:`pygmt.params.Axis` object. Raw GMT
+            strings or sequences of strings are also supported for backward
+            compatibility. If ``frame=True``, the frame will be drawn with the default
+            attributes. If ``frame="none"``, no frame will be drawn. Use a
+            :class:`pygmt.params.Frame` or :class:`pygmt.params.Axis` object for more
+            control over the attributes of the frame and axes. A tutorial is available at
+            :doc:`frame and axes attributes </tutorials/basics/frames>`. Full
+            documentation is at :gmt-docs:`gmt.html#b-full`.""",
     "gap": r"""
         gap : str or list
             **x**\|\ **y**\|\ **z**\|\ **d**\|\ **X**\|\ **Y**\|\