Merge branch 'main' into to_numpy/skip-macos

.github/workflows/check-links.yml

@@ -35,7 +35,7 @@ jobs:
 
     - name: Link Checker
       id: lychee
-      uses: lycheeverse/lychee-action@v2.0.2
+      uses: lycheeverse/lychee-action@v2.1.0
       with:
         fail: false  # Don't fail action on broken links
         output: /tmp/lychee-out.md

.github/workflows/ci_tests.yaml

@@ -177,10 +177,10 @@ jobs:
 
       # Upload coverage to Codecov
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v4.6.0
+        uses: codecov/codecov-action@v5.0.3
         if: success() || failure()
         with:
           use_oidc: true
-          file: ./coverage.xml # optional
+          files: ./coverage.xml # optional
           env_vars: OS,PYTHON,NUMPY
           fail_ci_if_error: false

doc/maintenance.md

@@ -120,18 +120,25 @@ made to our documentation website every time we make a commit in a pull request.
 The service has a configuration file `.readthedocs.yaml`, with a list of options
 to change the default behaviour at <https://docs.readthedocs.io/en/stable/config-file/index.html>.
 
+## Continuous Benchmarking
 
-## Dependencies Policy
+We use the [CodSpeed](https://codspeed.io) service to continuously track PyGMT's
+performance. The `pytest-codspeed` plugin collects benchmark data and uploads it to the
+CodSpeed server, where results are available at <https://codspeed.io/GenericMappingTools/pygmt>.
 
-PyGMT has adopted [SPEC 0](https://scientific-python.org/specs/spec-0000/) alongside the
-rest of the scientific Python ecosystem, and therefore:
+Benchmarking is handled through the `benchmarks.yml` GitHub Actions workflow. It's
+automatically executed when a pull request is merged into the main branch. To trigger
+benchmarking in a pull request, add the `run/benchmark` label to the pull request.
 
-* Support for Python versions be dropped 3 years after their initial release.
-* Support for core package dependencies (NumPy, pandas, Xarray) be dropped 2 years after
-  their initial release.
+To include a new test in the benchmark suite, apply the `@pytest.mark.benchmark`
+decorator to a test function.
 
-Similarly, the PyGMT team has decided to discontinue support for GMT versions 3 years
-after their initial release.
+## Dependencies Policy
+
+PyGMT has adopted [SPEC 0](https://scientific-python.org/specs/spec-0000/) alongside the
+rest of the scientific Python ecosystem, and made a few extensions based on the needs of
+the project. Please see [Minimum Supported Versions](minversions.md) for the detailed
+policy and the minimum supported versions of GMT, Python and core package dependencies.
 
 In `pyproject.toml`, the `requires-python` key should be set to the minimum supported
 version of Python. Minimum supported versions of GMT, Python and core package

examples/gallery/images/cross_section.py

@@ -2,13 +2,11 @@
 Cross-section along a transect
 ==============================
 
-:func:`pygmt.project` and :func:`pygmt.grdtrack` can be used to focus on
-a quantity and its variation along a desired survey line.
-In this example, the elevation is extracted from a grid provided via
-:func:`pygmt.datasets.load_earth_relief`.
-The figure consists of two parts, a map of the elevation in the study
-area showing the survey line and a Cartesian plot showing the elevation
-along the survey line.
+:func:`pygmt.project` and :func:`pygmt.grdtrack` can be used to focus on a quantity and
+its variation along a desired survey line. In this example, the elevation is extracted
+from a grid provided via :func:`pygmt.datasets.load_earth_relief`. The figure consists
+of two parts, a map of the elevation in the study area showing the survey line and a
+Cartesian plot showing the elevation along the survey line.
 
 *This example is orientated on an example in the GMT/China documentation*:
 https://docs.gmt-china.org/latest/examples/ex026/
@@ -27,33 +25,24 @@
 # ----------------------------------------------------------------------------
 # Bottom: Map of elevation in study area
 
-# Set up basic map
-fig.basemap(
-    region=region_map,
-    projection="M12c",  # Mercator projection with a width of 12 centimeters
-    frame="af",
-)
+# Set up basic map using a Mercator projection with a width of 12 centimeters
+fig.basemap(region=region_map, projection="M12c", frame="af")
 
-# Download grid for Earth relief with a resolution of 10 arc-minutes and
-# gridline registration [Default]
-grid_map = pygmt.datasets.load_earth_relief(
-    resolution="10m",
-    region=region_map,
-)
+# Download grid for Earth relief with a resolution of 10 arc-minutes and gridline
+# registration [Default]
+grid_map = pygmt.datasets.load_earth_relief(resolution="10m", region=region_map)
 
 # Plot the downloaded grid with color-coding based on the elevation
 fig.grdimage(grid=grid_map, cmap="oleron")
 
 # Add a colorbar for the elevation
 fig.colorbar(
-    # Place the colorbar inside the plot (lower-case "j") in the Bottom
-    # Right (BR) corner with an offset ("+o") of 0.7 centimeters and
-    # 0.3 centimeters in x or y directions, respectively
-    # Move the x label above the horizontal colorbar ("+ml")
+    # Place the colorbar inside the plot (lower-case "j") in the Botton Right (BR)
+    # corner with an offset ("+o") of 0.7 centimeters and 0.3 centimeters in x or y
+    # directions, respectively; move the x label above the horizontal colorbar ("+ml")
     position="jBR+o0.7c/0.8c+h+w5c/0.3c+ml",
-    # Add a box around the colobar with a fill ("+g") in "white" color and
-    # a transparency ("@") of 30 % and with a 0.8-points thick black
-    # outline ("+p")
+    # Add a box around the colobar with a fill ("+g") in "white" color and a
+    # transparency ("@") of 30 % and with a 0.8-points thick, black, outline ("+p")
     box="+gwhite@30+p0.8p,black",
     # Add x and y labels ("+l")
     frame=["x+lElevation", "y+lm"],
@@ -63,7 +52,7 @@
 fig.plot(
     x=[126, 146],  # Longitude in degrees East
     y=[42, 40],  # Latitude in degrees North
-    # Draw a 2-points thick red dashed line for the survey line
+    # Draw a 2-points thick, red, dashed line for the survey line
     pen="2p,red,dashed",
 )
 
@@ -79,16 +68,15 @@
 # ----------------------------------------------------------------------------
 # Top: Elevation along survey line
 
-# Shift plot origin 12.5 centimeters to the top
-fig.shift_origin(yshift="12.5c")
+# Shift plot origin to the top by the height of the map ("+h") plus 1.5 centimeters
+fig.shift_origin(yshift="h+1.5c")
 
 fig.basemap(
     region=[0, 15, -8000, 6000],  # x_min, x_max, y_min, y_max
-    # Cartesian projection with a width of 12 centimeters and
-    # a height of 3 centimeters
+    # Cartesian projection with a width of 12 centimeters and a height of 3 centimeters
     projection="X12c/3c",
-    # Add annotations ("a") and ticks ("f") as well as labels ("+l")
-    # at the west or left and south or bottom sides ("WSrt")
+    # Add annotations ("a") and ticks ("f") as well as labels ("+l") at the west or
+    # left and south or bottom sides ("WSrt")
     frame=["WSrt", "xa2f1+lDistance+u°", "ya4000+lElevation / m"],
 )
 
@@ -101,28 +89,24 @@
     font="10p",  # Use a font size of 10 points
 )
 
-# Generate points along a great circle corresponding to the survey line
-# and store them in a pandas.DataFrame
+# Generate points along a great circle corresponding to the survey line and store them
+# in a pandas.DataFrame
 track_df = pygmt.project(
-    center="126/42",  # Start point of survey line (longitude/latitude)
-    endpoint="146/40",  # End point of survey line (longitude/latitude)
-    generate="0.1",  # Output data in steps of 0.1 degrees
+    center=[126, 42],  # Start point of survey line (longitude, latitude)
+    endpoint=[146, 40],  # End point of survey line (longitude, latitude)
+    generate=0.1,  # Output data in steps of 0.1 degrees
 )
 
-# Extract the elevation at the generated points from the downloaded grid
-# and add it as new column "elevation" to the pandas.DataFrame
-track_df = pygmt.grdtrack(
-    grid=grid_map,
-    points=track_df,
-    newcolname="elevation",
-)
+# Extract the elevation at the generated points from the downloaded grid and add it as
+# new column "elevation" to the pandas.DataFrame
+track_df = pygmt.grdtrack(grid=grid_map, points=track_df, newcolname="elevation")
 
 # Plot water masses
 fig.plot(
     x=[0, 15],
     y=[0, 0],
     fill="lightblue",  # Fill the polygon in "lightblue"
-    # Draw a 0.25-points thick black solid outline
+    # Draw a 0.25-points thick, black, solid outline
     pen="0.25p,black,solid",
     close="+y-8000",  # Force closed polygon
 )
@@ -132,7 +116,7 @@
     x=track_df.p,
     y=track_df.elevation,
     fill="gray",  # Fill the polygon in "gray"
-    # Draw a 1-point thick black solid outline
+    # Draw a 1-point thick, black, solid outline
     pen="1p,black,solid",
     close="+y-8000",  # Force closed polygon
 )

examples/gallery/lines/envelope.py

@@ -2,18 +2,18 @@
 Envelope
 ========
 
-The ``close`` parameter of the :meth:`pygmt.Figure.plot` method can be
-used to build a symmetrical or an asymmetrical envelope. The user can
-give either the deviations or the bounds in y-direction. For the first
-case append ``"+d"`` or ``"+D"`` and for the latter case ``"+b"``.
+The ``close`` parameter of the :meth:`pygmt.Figure.plot` method can be used to build a
+symmetrical or an asymmetrical envelope. The user can give either the deviations or the
+bounds in y-direction. For the first case append ``"+d"`` or ``"+D"`` and for the latter
+case ``"+b"``.
 """
 
 # %%
 import pandas as pd
 import pygmt
 
-# Define a pandas DataFrame with columns for x and y as well as the
-# lower and upper deviations
+# Define a pandas.DataFrame with columns for x and y as well as the lower and upper
+# deviations
 df_devi = pd.DataFrame(
     data={
         "x": [1, 3, 5, 7, 9],
@@ -23,7 +23,7 @@
     }
 )
 
-# Define the same pandas DataFrame but with lower and upper bounds
+# Define the same pandas.DataFrame but with lower and upper bounds
 df_bound = pd.DataFrame(
     data={
         "x": [1, 3, 5, 7, 9],
@@ -34,7 +34,6 @@
 )
 
 
-# Create Figure instance
 fig = pygmt.Figure()
 
 # -----------------------------------------------------------------------------
@@ -55,15 +54,10 @@
 )
 
 # Plot the data points on top
-fig.plot(
-    data=df_devi,
-    style="c0.2c",  # Use circles with a diameter of 0.2 centimeters
-    pen="1p,gray30",
-    fill="darkgray",
-)
+fig.plot(data=df_devi, style="c0.2c", pen="1p,gray30", fill="darkgray")
 
-# Shift plot origin 11 centimeters in x direction
-fig.shift_origin(xshift="11c")
+# Shift plot origin by the figure width ("w") plus 1 centimeter in x direction
+fig.shift_origin(xshift="w+1c")
 
 # -----------------------------------------------------------------------------
 # Middle
@@ -77,18 +71,15 @@
 fig.plot(
     data=df_devi,
     fill="gray@50",
-    # Add an outline around the envelope
-    # Here, a dashed pen ("+p") with 0.5-points thickness and
-    # "gray30" color is used
+    # Add an outline around the envelope. Here, a dashed pen ("+p") with 0.5-points
+    # thickness and "gray30" color is used
     close="+D+p0.5p,gray30,dashed",
     pen="1p,gray30",
 )
 
-# Plot the data points on top
 fig.plot(data=df_devi, style="c0.2c", pen="1p,gray30", fill="darkgray")
 
-# Shift plot origin 11 centimeters in x-direction
-fig.shift_origin(xshift="11c")
+fig.shift_origin(xshift="w+1c")
 
 # -----------------------------------------------------------------------------
 # Right
@@ -102,7 +93,6 @@
 # Plot an envelope based on the bounds ("+b")
 fig.plot(data=df_bound, close="+b+p0.5p,gray30,dashed", pen="1p,gray30")
 
-# Plot the data points on top
 fig.plot(data=df_bound, style="c0.2c", pen="1p,gray30", fill="darkgray")
 
 fig.show()

examples/gallery/symbols/multi_parameter_symbols.py

@@ -2,9 +2,9 @@
 Multi-parameter symbols
 =======================
 
-The :meth:`pygmt.Figure.plot` method can plot individual multi-parameter
-symbols by passing the corresponding shortcuts (**e**, **j**, **r**, **R**,
-**w**) to the ``style`` parameter:
+The :meth:`pygmt.Figure.plot` method can plot individual multi-parameter symbols by
+passing the corresponding shortcuts (**e**, **j**, **r**, **R**, **w**) to the ``style``
+parameter:
 
 - **e**: ellipse
 - **j**: rotated rectangle
@@ -18,10 +18,10 @@
 import pygmt
 
 # %%
-# We can plot multi-parameter symbols using the same symbol style. We need to
-# define locations (lon, lat) via the ``x`` and ``y`` parameters (scalar for
-# a single symbol or 1-D list for several ones) and two or three symbol
-# parameters after those shortcuts via the ``style`` parameter.
+# We can plot multi-parameter symbols using the same symbol style. We need to define
+# locations (lon, lat) via the ``x`` and ``y`` parameters (scalar for a single symbol or
+# 1-D list for several ones) and two or three symbol parameters after those shortcuts
+# via the ``style`` parameter.
 #
 # The multi-parameter symbols in the ``style`` parameter are defined as:
 #
@@ -30,13 +30,14 @@
 # - **r**: rectangle, ``width/height``
 # - **R**: rounded rectangle, ``width/height/radius``
 # - **w**: pie wedge, ``diameter/startdir/stopdir``, the last two arguments are
-#   directions given in degrees counter-clockwise from horizontal
+#   directions given in degrees counter-clockwise from horizontal. Append **+i** and the
+#   desired value to apply an inner diameter.
 #
-# Upper-case versions **E**, **J**, and **W** are similar to **e**, **j**, and
-# **w** but expect geographic azimuths and distances.
+# Upper-case versions **E**, **J**, and **W** are similar to **e**, **j**, and **w**
+# but expect geographic azimuths and distances.
 
 fig = pygmt.Figure()
-fig.basemap(region=[0, 6, 0, 2], projection="x3c", frame=True)
+fig.basemap(region=[0, 7, 0, 2], projection="x3c", frame=True)
 
 # Ellipse
 fig.plot(x=0.5, y=1, style="e45/3/1", fill="orange", pen="2p,black")
@@ -48,27 +49,28 @@
 fig.plot(x=4.5, y=1, style="R1.25/4/0.5", fill="seagreen", pen="2p,black")
 # Pie wedge
 fig.plot(x=5.5, y=1, style="w2.5/45/330", fill="lightgray", pen="2p,black")
+# Ring sector
+fig.plot(x=6.5, y=1, style="w2.5/45/330+i1", fill="lightgray", pen="2p,black")
 
 fig.show()
 
 # %%
-# We can also plot symbols with varying parameters via defining those values in
-# a 2-D list or numpy array (``[[parameters]]`` for a single symbol or
-# ``[[parameters_1],[parameters_2],[parameters_i]]`` for several ones) or using
-# an appropriately formatted input file and passing it to ``data``.
+# We can also plot symbols with varying parameters via defining those values in a 2-D
+# list or numpy array (``[[parameters]]`` for a single symbol or
+# ``[[parameters_1],[parameters_2],[parameters_i]]`` for several ones) or using an
+# appropriately formatted input file and passing it to ``data``.
 #
 # The symbol parameters in the 2-D list or numpy array are defined as:
 #
 # - **e**: ellipse, ``[[lon, lat, direction, major_axis, minor_axis]]``
 # - **j**: rotated rectangle, ``[[lon, lat, direction, width, height]]``
 # - **r**: rectangle, ``[[lon, lat, width, height]]``
 # - **R**: rounded rectangle, ``[[lon, lat, width, height, radius]]``
-# - **w**: pie wedge, ``[[lon, lat, diameter, startdir, stopdir]]``, the last
-#   two arguments are directions given in degrees counter-clockwise from
-#   horizontal
+# - **w**: pie wedge, ``[[lon, lat, diameter, startdir, stopdir]]``, the last two
+#   arguments are directions given in degrees counter-clockwise from horizontal
 
 fig = pygmt.Figure()
-fig.basemap(region=[0, 6, 0, 4], projection="x3c", frame=["xa1f0.2", "ya0.5f0.1"])
+fig.basemap(region=[0, 7, 0, 4], projection="x3c", frame=["xa1f0.2", "ya0.5f0.1"])
 
 # Ellipse
 data = [[0.5, 1, 45, 3, 1], [0.5, 3, 135, 2, 1]]
@@ -85,6 +87,9 @@
 # Pie wedge
 data = [[5.5, 1, 2.5, 45, 330], [5.5, 3, 1.5, 60, 300]]
 fig.plot(data=data, style="w", fill="lightgray", pen="2p,black")
+# Ring sector
+data = [[6.5, 1, 2.5, 45, 330], [6.5, 3, 1.5, 60, 300]]
+fig.plot(data=data, style="w+i1", fill="lightgray", pen="2p,black")
 
 fig.show()