pygmt.grdclip: Deprecate parameter 'new' to 'replace' (remove in v0.19.0) (#3884)

Author: seisman

pygmt/src/grdclip.py

@@ -4,18 +4,26 @@
 
 import xarray as xr
 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,
+)
 
 __doctest_skip__ = ["grdclip"]
 
 
+# TODO(PyGMT>=0.19.0): Remove the deprecated "new" parameter.
 @fmt_docstring
+@deprecate_parameter("new", "replace", "v0.15.0", remove_version="v0.19.0")
 @use_alias(
     R="region",
     Sa="above",
     Sb="below",
     Si="between",
-    Sr="new",
+    Sr="replace",
     V="verbose",
 )
 @kwargs_to_strings(
@@ -55,7 +63,7 @@ def grdclip(grid, outgrid: str | None = None, **kwargs) -> xr.DataArray | None:
     between : str or list
         [*low*, *high*, *between*].
         Set all data[i] >= *low* and <= *high* to *between*.
-    new : str or list
+    replace : str or list
         [*old*, *new*].
         Set all data[i] == *old* to *new*. This is mostly useful when
         your data are known to be integer values.

pygmt/tests/test_grdclip.py

@@ -4,9 +4,12 @@
 
 from pathlib import Path
 
+import numpy as np
+import numpy.testing as npt
 import pytest
 import xarray as xr
 from pygmt import grdclip, load_dataarray
+from pygmt.datasets import load_earth_mask
 from pygmt.enums import GridRegistration, GridType
 from pygmt.helpers import GMTTempFile
 from pygmt.helpers.testing import load_static_earth_relief
@@ -69,3 +72,19 @@ def test_grdclip_no_outgrid(grid, expected_grid):
     assert temp_grid.gmt.gtype == GridType.GEOGRAPHIC
     assert temp_grid.gmt.registration == GridRegistration.PIXEL
     xr.testing.assert_allclose(a=temp_grid, b=expected_grid)
+
+
+def test_grdclip_replace():
+    """
+    Test the replace parameter for grdclip.
+    """
+    grid = load_earth_mask(region=[0, 10, 0, 10])
+    npt.assert_array_equal(np.unique(grid), [0, 1])  # Only have 0 and 1
+    grid = grdclip(grid=grid, replace=[0, 2])  # Replace 0 with 2
+    npt.assert_array_equal(np.unique(grid), [1, 2])
+
+    # Test for the deprecated 'new' parameter
+    # TODO(PyGMT>=0.19.0): Remove this test below for the 'new' parameter
+    with pytest.warns(FutureWarning):
+        grid = grdclip(grid=grid, new=[1, 3])  # Replace 1 with 3
+        npt.assert_array_equal(np.unique(grid), [2, 3])