Merge branch 'main' into feature/magnetic_rose

Author: michaelgrund

.github/workflows/benchmarks.yml

@@ -84,7 +84,7 @@ jobs:
 
       # Run the benchmark tests
       - name: Run benchmarks
-        uses: CodSpeedHQ/action@6a8e2b874c338bf81cc5e8be715ada75908d3871 # v4.3.4
+        uses: CodSpeedHQ/action@346a2d8a8d9d38909abd0bc3d23f773110f076ad # v4.4.1
         with:
           mode: "instrumentation"
           # 'bash -el -c' is needed to use the custom shell.

.github/workflows/ci_tests.yaml

@@ -151,7 +151,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
+        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
         with:
           activate-environment: true
           python-version: ${{ matrix.python-version }}

doc/contributing.md

@@ -488,10 +488,10 @@ integration systems will warn us and you can make a new commit with the formatte
 Even better, you can just write `/format` in the first line of any comment in a
 pull request to lint the code automatically.
 
-When wrapping a new alias, use an underscore to separate words bridged by vowels
-(aeiou), such as `no_skip` and `z_only`. Do not use an underscore to separate
-words bridged only by consonants, such as `distcalc`, and `crossprofile`. This
-convention is not applied by the code checking tools, but the PyGMT maintainers
+When introducing a new parameter name, use an underscore to separate words. This improves
+readability and aligns with the [PEP 8 style guide](https://peps.python.org/pep-0008/).
+For common shortcuts no underscore is needed, e.g., `surftype`, `outgrid`, or `timefmt`.
+This convention is not applied by the code checking tools, but the PyGMT maintainers
 will comment on any pull requests as needed.
 
 When working on a tutorial or a gallery plot, it is good practice to use code

examples/tutorials/advanced/cartesian_histograms.py

@@ -320,7 +320,7 @@
 # Grouped bars
 # ------------
 #
-# By setting the ``barwidth`` parameter in respect to the values passed to the
+# By setting the ``bar_width`` parameter in respect to the values passed to the
 # ``series`` parameter histograms with grouped bars can be created.
 #
 # Limitations of histograms with grouped bars are:
@@ -347,7 +347,7 @@
     # of the bin width
     # Offset ("+o") the bars to align each bar with the left limit of the corresponding
     # bin
-    barwidth=f"{binwidth / 2}+o-{binwidth / 4}",
+    bar_width=f"{binwidth / 2}+o-{binwidth / 4}",
     label="data01",
 )
 
@@ -358,7 +358,7 @@
     fill="orange",
     pen="1p,darkgray,solid",
     histtype=0,
-    barwidth=f"{binwidth / 2}+o{binwidth / 4}",
+    bar_width=f"{binwidth / 2}+o{binwidth / 4}",
     label="data02",
 )
 

pygmt/src/grdview.py

@@ -6,10 +6,12 @@
 from typing import Literal
 
 import xarray as xr
+from packaging.version import Version
 from pygmt._typing import PathLike
 from pygmt.alias import Alias, AliasSystem
-from pygmt.clib import Session
+from pygmt.clib import Session, __gmt_version__
 from pygmt.helpers import build_arg_list, deprecate_parameter, fmt_docstring, use_alias
+from pygmt.src.grdinfo import grdinfo
 
 __doctest_skip__ = ["grdview"]
 
@@ -116,6 +118,8 @@ def grdview(  # noqa: PLR0913
         value in the grid. However, if ``region`` was used to set *zmin/zmax* then
         *zmin* is used if it is less than the grid minimum value. Use ``facade_pen`` and
         ``facade_fill`` to control the appearance of the plane.
+        **Note**: For GMT<=6.6.0, *zmin* set in ``region`` has no effect due to a GMT
+        bug.
     facade_fill
         Fill for the frontal facade between the plane specified by ``plane`` and the
         data perimeter.
@@ -174,6 +178,18 @@ def grdview(  # noqa: PLR0913
     if plane is False and (facade_fill is not None or facade_pen is not None):
         plane = True
 
+    # Workaround for GMT bug https://github.com/GenericMappingTools/gmt/pull/8838
+    # Fix the plane value to be the grid minimum if plane=True.
+    # Notes:
+    # 1. It's the minimum of the grid, not a subset of the grid defined by 'region'.
+    # 2. The GMT docs says "if -R was used to set zmin/zmax then we use that value if
+    #    it is less than the grid minimum value.". We can't add a workaround for this
+    #    case since we can't parse zmin/zmax from 'region' if 'region' was set in
+    #    previous plotting commands.
+    # TODO(GMT>6.6.0): Remove this workaround.
+    if Version(__gmt_version__) <= Version("6.6.0") and plane is True:
+        plane = grdinfo(grid, per_column=True).split()[4]
+
     aliasdict = AliasSystem(
         Jz=Alias(zscale, name="zscale"),
         JZ=Alias(zsize, name="zsize"),

pygmt/src/histogram.py

@@ -8,15 +8,22 @@
 from pygmt._typing import PathLike, TableLike
 from pygmt.alias import AliasSystem
 from pygmt.clib import Session
-from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.helpers import (
+    build_arg_list,
+    deprecate_parameter,
+    fmt_docstring,
+    kwargs_to_strings,
+    use_alias,
+)
 
 
 @fmt_docstring
+@deprecate_parameter("barwidth", "bar_width", "v0.18.0", remove_version="v0.20.0")
 @use_alias(
     A="horizontal",
     C="cmap",
     D="annotate",
-    E="barwidth",
+    E="bar_width",
     F="center",
     G="fill",
     L="extreme",
@@ -84,7 +91,7 @@ def histogram(
         annotation font; use **+o** to change the offset between bar and
         label [Default is ``"6p"``]; use **+r** to rotate the labels from
         horizontal to vertical.
-    barwidth : float or str
+    bar_width : float or str
         *width*\ [**+o**\ *offset*].
         Use an alternative histogram bar width than the default set via
         ``series``, and optionally shift all bars by an *offset*. Here

pygmt/src/select.py

@@ -12,6 +12,7 @@
 from pygmt.clib import Session
 from pygmt.helpers import (
     build_arg_list,
+    deprecate_parameter,
     fmt_docstring,
     kwargs_to_strings,
     use_alias,
@@ -22,14 +23,16 @@
 
 
 @fmt_docstring
+@deprecate_parameter("mask", "mask_values", "v0.18.0", remove_version="v0.20.0")
+@deprecate_parameter("gridmask", "mask_grid", "v0.18.0", remove_version="v0.20.0")
 @use_alias(
     A="area_thresh",
     C="dist2pt",
     F="polygon",
-    G="gridmask",
+    G="mask_grid",
     I="reverse",
     L="dist2line",
-    N="mask",
+    N="mask_values",
     Z="z_subregion",
     b="binary",
     d="nodata",
@@ -128,42 +131,40 @@ def select(
         <reference/file-formats.html#optional-segment-header-records>`
         *polygonfile*. For spherical polygons (lon, lat), make sure no
         consecutive points are separated by 180 degrees or more in longitude.
-    gridmask : str
+    mask_grid : str
         Pass all locations that are inside the valid data area of the grid
-        *gridmask*. Nodes that are outside are either NaN or zero.
+        *mask_grid*. Nodes that are outside are either NaN or zero.
     reverse : str
         [**cflrsz**].
         Reverse the sense of the test for each of the criteria specified:
 
         - **c** select records NOT inside any point's circle of influence.
         - **f** select records NOT inside any of the polygons.
         - **g** will pass records inside the cells with z equal zero of the
-          grid mask in ``gridmask``.
+          *mask_grid* in ``mask_grid``.
         - **l** select records NOT within the specified distance of any line.
         - **r** select records NOT inside the specified rectangular region.
-        - **s** select records NOT considered inside as specified by ``mask``
+        - **s** select records NOT considered inside as specified by ``mask_values``
           (and ``area_thresh``, ``resolution``).
         - **z** select records NOT within the range specified by
           ``z_subregion``.
     $projection
-    mask : str or list
-        Pass all records whose location is inside specified geographical
-        features. Specify if records should be skipped (s) or kept (k) using
-        1 of 2 formats:
+    mask_values : str or list
+        Pass all records whose location is inside specified geographical features.
+        Specify if records should be skipped (s) or kept (k) using 1 of 2 formats:
 
         - *wet/dry*.
         - *ocean/land/lake/island/pond*.
 
-        [Default is s/k/s/k/s (i.e., s/k), which passes all points on dry
-        land].
+        [Default is s/k/s/k/s (i.e., s/k), which passes all points on dry land].
     resolution
-        Ignored unless ``mask`` is set. Select the resolution of the coastline dataset
-        to use. The available resolutions from highest to lowest are: ``"full"``,
-        ``"high"``, ``"intermediate"``, ``"low"``, and ``"crude"``, which drops by 80%
-        between levels. Alternatively, choose ``"auto"`` to automatically select the
-        most suitable resolution given the chosen region. Note that because the
-        coastlines differ in details, a node in a mask file using one resolution is not
-        guaranteed to remain inside [or outside] when a different resolution is
+        Ignored unless ``mask_values`` is set. Select the resolution of the coastline
+        dataset to use. The available resolutions from highest to lowest are:
+        ``"full"``, ``"high"``, ``"intermediate"``, ``"low"``, and ``"crude"``, which
+        drops by 80% between levels. Alternatively, choose ``"auto"`` to automatically
+        select the most suitable resolution given the chosen region. Note that because
+        the coastlines differ in details, a node in a mask file using one resolution is
+        not guaranteed to remain inside [or outside] when a different resolution is
         selected. If ``None``, the low resolution is used by default.
     $region
     $verbose

pygmt/tests/baseline/test_grdview_facadepen_default_plane.png.dvc

@@ -1,5 +1,5 @@
 outs:
-- md5: cfff4879fbe7ab03d8a304b2622b9782
-  size: 26208
+- md5: aa725f7d05462e7d272cf7045a7c9913
+  size: 32037
   hash: md5
   path: test_grdview_facadepen_default_plane.png