pygmt.grdlandmask: Deprecate parameters bordervalues/maskvalues to broder_values/mask_values (Will be removed in v0.20.0) (#4281)

Author: yvonnefroehlich

examples/gallery/images/grdlandmask.py

@@ -3,7 +3,7 @@
 ==========================
 
 The :func:`pygmt.grdlandmask` function allows setting all nodes on land
-or water to a specified value using the ``maskvalues`` parameter.
+or water to a specified value using the ``mask_values`` parameter.
 """
 
 # %%
@@ -18,7 +18,9 @@
 # masses.
 # Use shoreline data with (l)ow resolution and set the grid spacing to
 # 5 arc-minutes in x- and y-directions.
-grid = pygmt.grdlandmask(region=region, spacing="5m", maskvalues=[0, 1], resolution="l")
+grid = pygmt.grdlandmask(
+    region=region, spacing="5m", mask_values=[0, 1], resolution="l"
+)
 
 # Plot clipped grid
 fig.basemap(region=region, projection="M12c", frame=True)

pygmt/src/grdlandmask.py

@@ -10,18 +10,22 @@
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
+from pygmt.helpers import build_arg_list, deprecate_parameter, fmt_docstring, use_alias
 
 __doctest_skip__ = ["grdlandmask"]
 
 
 @fmt_docstring
+@deprecate_parameter("maskvalues", "mask_values", "v0.18.0", remove_version="v0.20.0")
+@deprecate_parameter(
+    "bordervalues", "border_values", "v0.18.0", remove_version="v0.20.0"
+)
 @use_alias(A="area_thresh")
 def grdlandmask(
     outgrid: PathLike | None = None,
     spacing: Sequence[float | str] | None = None,
-    maskvalues: Sequence[float] | None = None,
-    bordervalues: bool | float | Sequence[float] | None = None,
+    mask_values: Sequence[float] | None = None,
+    border_values: bool | float | Sequence[float] | None = None,
     resolution: Literal[
         "auto", "full", "high", "intermediate", "low", "crude", None
     ] = None,
@@ -45,9 +49,9 @@ def grdlandmask(
 
     $aliases
        - D = resolution
-       - E = bordervalues
+       - E = border_values
        - I = spacing
-       - N = maskvalues
+       - N = mask_values
        - R = region
        - V = verbose
        - r = registration
@@ -68,15 +72,15 @@ def grdlandmask(
         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.
-    maskvalues
+    mask_values
         Set the values that will be assigned to nodes, in the form of [*wet*, *dry*], or
         [*ocean*, *land*, *lake*, *island*, *pond*]. Default is ``[0, 1, 0, 1, 0]``
         (i.e., ``[0, 1]``), meaning that all "wet" nodes will be assigned a value of 0
         and all "dry" nodes will be assigned a value of 1. Values can be any number, or
         one of ``None``, ``"NaN"``, and ``np.nan`` for setting nodes to NaN.
 
-        Use ``bordervalues`` to control how nodes on feature boundaries are handled.
-    bordervalues
+        Use ``border_values`` to control how nodes on feature boundaries are handled.
+    border_values
         Sets the behavior for nodes that fall exactly on a polygon boundary. Valid
         values are:
 
@@ -129,8 +133,8 @@ def grdlandmask(
             },
         ),
         I=Alias(spacing, name="spacing", sep="/", size=2),
-        N=Alias(maskvalues, name="maskvalues", sep="/", size=(2, 5)),
-        E=Alias(bordervalues, name="bordervalues", sep="/", size=4),
+        N=Alias(mask_values, name="mask_values", sep="/", size=(2, 5)),
+        E=Alias(border_values, name="border_values", sep="/", size=4),
     ).add_common(
         R=region,
         V=verbose,