pygmt.grdfill: Deprecate parameters splinefill/constantfill/neighborfill/gridfill to spline_fill/constant_fill/neighbor_fill/grid_fill (Will be removed in v0.20.0) (#4273)

Author: yvonnefroehlich

pygmt/src/grdfill.py

@@ -18,24 +18,24 @@
 
 
 def _validate_params(
-    constantfill=None,
-    gridfill=None,
-    neighborfill=None,
-    splinefill=None,
+    constant_fill=None,
+    grid_fill=None,
+    neighbor_fill=None,
+    spline_fill=None,
     inquire=False,
     mode=None,
 ):
     """
     Validate the fill/inquire parameters.
 
-    >>> _validate_params(constantfill=20.0)
+    >>> _validate_params(constant_fill=20.0)
     >>> _validate_params(inquire=True)
     >>> _validate_params(mode="c20.0")
-    >>> _validate_params(constantfill=20.0, gridfill="bggrid.nc")
+    >>> _validate_params(constant_fill=20.0, grid_fill="bggrid.nc")
     Traceback (most recent call last):
     ...
     pygmt.exceptions.GMTInvalidInput: Parameters ... are mutually exclusive.
-    >>> _validate_params(constantfill=20.0, inquire=True)
+    >>> _validate_params(constant_fill=20.0, inquire=True)
     Traceback (most recent call last):
     ...
     pygmt.exceptions.GMTInvalidInput: Parameters ... are mutually exclusive.
@@ -44,7 +44,7 @@ def _validate_params(
     ...
     pygmt.exceptions.GMTInvalidInput: Need to specify parameter ...
     """
-    _fill_params = "'constantfill'/'gridfill'/'neighborfill'/'splinefill'"
+    _fill_params = "'constant_fill'/'grid_fill'/'neighbor_fill'/'spline_fill'"
     # The deprecated 'mode' parameter is given.
     if mode is not None:
         msg = (
@@ -55,7 +55,14 @@ def _validate_params(
 
     n_given = sum(
         param is not None and param is not False
-        for param in [constantfill, gridfill, neighborfill, splinefill, inquire, mode]
+        for param in [
+            constant_fill,
+            grid_fill,
+            neighbor_fill,
+            spline_fill,
+            inquire,
+            mode,
+        ]
     )
     if n_given > 1:  # More than one mutually exclusive parameter is given.
         msg = f"Parameters {_fill_params}/'inquire'/'mode' are mutually exclusive."
@@ -71,15 +78,23 @@ def _validate_params(
 @fmt_docstring
 # TODO(PyGMT>=0.19.0): Remove the deprecated 'no_data' parameter.
 # TODO(PyGMT>=0.19.0): Remove the deprecated 'mode' parameter.
-@deprecate_parameter("no_data", "hole", "v0.15.0", remove_version="v0.19.0")
+@deprecate_parameter("no_data", "hole", "v0.18.0", remove_version="v0.20.0")
+@deprecate_parameter(
+    "constantfill", "constant_fill", "v0.15.0", remove_version="v0.19.0"
+)
+@deprecate_parameter("gridfill", "grid_fill", "v0.18.0", remove_version="v0.20.0")
+@deprecate_parameter(
+    "neighborfill", "neighbor_fill", "v0.18.0", remove_version="v0.20.0"
+)
+@deprecate_parameter("splinefill", "spline_fill", "v0.18.0", remove_version="v0.20.0")
 @use_alias(f="coltypes")
 def grdfill(  # noqa: PLR0913
     grid: PathLike | xr.DataArray,
     outgrid: PathLike | None = None,
-    constantfill: float | None = None,
-    gridfill: PathLike | xr.DataArray | None = None,
-    neighborfill: float | bool | None = None,
-    splinefill: float | bool | None = None,
+    constant_fill: float | None = None,
+    grid_fill: PathLike | xr.DataArray | None = None,
+    neighbor_fill: float | bool | None = None,
+    spline_fill: float | bool | None = None,
     inquire: bool = False,
     hole: float | None = None,
     mode: str | None = None,
@@ -100,10 +115,10 @@ def grdfill(  # noqa: PLR0913
     Full GMT docs at :gmt-docs:`grdfill.html`.
 
     $aliases
-       - Ac = constantfill
-       - Ag = gridfill
-       - An = neighborfill
-       - As = splinefill
+       - Ac = constant_fill
+       - Ag = grid_fill
+       - An = neighbor_fill
+       - As = spline_fill
        - L = inquire
        - N = hole
        - R = region
@@ -113,17 +128,17 @@ def grdfill(  # noqa: PLR0913
     ----------
     $grid
     $outgrid
-    constantfill
+    constant_fill
         Fill the holes with a constant value. Specify the constant value to use.
-    gridfill
+    grid_fill
         Fill the holes with values sampled from another (possibly coarser) grid. Specify
         the grid (a file name or an :class:`xarray.DataArray`) to use for the fill.
-    neighborfill
+    neighbor_fill
         Fill the holes with the nearest neighbor. Specify the search radius in pixels.
         If set to ``True``, the default search radius will be used
         (:math:`r^2 = \sqrt{n^2 + m^2}`, where (*n,m*) are the node dimensions of the
         grid).
-    splinefill
+    spline_fill
         Fill the holes with a bicubic spline. Specify the tension value to use. If set
         to ``True``, no tension will be used.
     hole
@@ -141,8 +156,9 @@ def grdfill(  # noqa: PLR0913
         (optionally append a *tension* parameter [Default is no tension]).
 
         .. deprecated:: 0.15.0
-            Use ``constantfill``, ``gridfill``, ``neighborfill``, or ``splinefill``
+            Use ``constant_fill``, ``grid_fill``, ``neighbor_fill``, or ``spline_fill``
             instead. The parameter will be removed in v0.19.0.
+
     $region
     $coltypes
     $verbose
@@ -165,7 +181,7 @@ def grdfill(  # noqa: PLR0913
     >>> # Load a bathymetric grid with missing data
     >>> earth_relief_holes = pygmt.datasets.load_sample_data(name="earth_relief_holes")
     >>> # Fill the holes with a constant value of 20
-    >>> filled_grid = pygmt.grdfill(grid=earth_relief_holes, constantfill=20)
+    >>> filled_grid = pygmt.grdfill(grid=earth_relief_holes, constant_fill=20)
 
     Inquire the bounds of each hole.
 
@@ -174,16 +190,18 @@ def grdfill(  # noqa: PLR0913
            [6.16666667, 7.83333333, 0.5       , 2.5       ]])
     """
     # Validate the fill/inquire parameters.
-    _validate_params(constantfill, gridfill, neighborfill, splinefill, inquire, mode)
+    _validate_params(
+        constant_fill, grid_fill, neighbor_fill, spline_fill, inquire, mode
+    )
 
     # _validate_params has already ensured that only one of the parameters is set.
     aliasdict = AliasSystem(
         A=Alias(mode, name="mode"),
-        Ac=Alias(constantfill, name="constantfill"),
-        # For grdfill, append the actual or virtual grid file name later.
-        Ag=Alias(gridfill is not None, name="gridfill"),
-        An=Alias(neighborfill, name="neighborfill"),
-        As=Alias(splinefill, name="splinefill"),
+        Ac=Alias(constant_fill, name="constant_fill"),
+        # For grid_fill, append the actual or virtual grid file name later.
+        Ag=Alias(grid_fill is not None, name="grid_fill"),
+        An=Alias(neighbor_fill, name="neighbor_fill"),
+        As=Alias(spline_fill, name="spline_fill"),
         L=Alias(inquire, name="inquire"),
         N=Alias(hole, name="hole"),
     ).add_common(
@@ -207,11 +225,11 @@ def grdfill(  # noqa: PLR0913
             # Fill mode.
             with (
                 lib.virtualfile_in(
-                    check_kind="raster", data=gridfill, required=False
+                    check_kind="raster", data=grid_fill, required=False
                 ) as vbggrd,
                 lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
             ):
-                if gridfill is not None:
+                if grid_fill is not None:
                     # Fill by a grid. Append the actual or virtual grid file name.
                     aliasdict["Ag"] = vbggrd
                 aliasdict["G"] = voutgrd

pygmt/tests/test_grdfill.py

@@ -62,7 +62,7 @@ def test_grdfill_dataarray_out(grid, expected_grid):
     """
     Test grdfill with a DataArray output.
     """
-    result = grdfill(grid=grid, constantfill=20)
+    result = grdfill(grid=grid, constant_fill=20)
     # check information of the output grid
     assert isinstance(result, xr.DataArray)
     assert result.gmt.gtype is GridType.GEOGRAPHIC
@@ -77,7 +77,7 @@ def test_grdfill_asymmetric_pad(grid, expected_grid):
 
     Regression test for https://github.com/GenericMappingTools/pygmt/issues/1745.
     """
-    result = grdfill(grid=grid, constantfill=20, region=[-55, -50, -24, -16])
+    result = grdfill(grid=grid, constant_fill=20, region=[-55, -50, -24, -16])
     # check information of the output grid
     assert isinstance(result, xr.DataArray)
     assert result.gmt.gtype is GridType.GEOGRAPHIC
@@ -93,14 +93,14 @@ def test_grdfill_file_out(grid, expected_grid):
     Test grdfill with an outgrid set.
     """
     with GMTTempFile(suffix=".nc") as tmpfile:
-        result = grdfill(grid=grid, constantfill=20, outgrid=tmpfile.name)
+        result = grdfill(grid=grid, constant_fill=20, outgrid=tmpfile.name)
         assert result is None  # return value is None
         assert Path(tmpfile.name).stat().st_size > 0  # check that outfile exists
         temp_grid = xr.load_dataarray(tmpfile.name, engine="gmt", raster_kind="grid")
         xr.testing.assert_allclose(a=temp_grid, b=expected_grid)
 
 
-def test_grdfill_gridfill_dataarray(grid):
+def test_grdfill_grid_fill_dataarray(grid):
     """
     Test grdfill with a DataArray input.
     """
@@ -109,7 +109,7 @@ def test_grdfill_gridfill_dataarray(grid):
         dims=grid.dims,
         coords={"lon": grid.lon, "lat": grid.lat},
     )
-    result = grdfill(grid=grid, gridfill=bggrid)
+    result = grdfill(grid=grid, grid_fill=bggrid)
     assert not result.isnull().any()
     npt.assert_array_equal(result[3:6, 3:5], bggrid[3:6, 3:5])
 
@@ -119,11 +119,11 @@ def test_grdfill_hole(grid, expected_grid):
     Test grdfill with a custom value (not NaN) as holes.
     """
     # Prepare for a grid with a node value of -99999 for holes.
-    grid_no_nan = grdfill(grid=grid, constantfill=-99999)
+    grid_no_nan = grdfill(grid=grid, constant_fill=-99999)
     assert not np.isnan(grid_no_nan).any()
     assert -99999 in grid_no_nan
     # Now fill them with a constant value of 20.
-    result = grdfill(grid=grid_no_nan, constantfill=20, hole=-99999)
+    result = grdfill(grid=grid_no_nan, constant_fill=20, hole=-99999)
 
     # Check information of the output grid
     assert isinstance(result, xr.DataArray)
@@ -134,7 +134,7 @@ def test_grdfill_hole(grid, expected_grid):
     # Test the deprecated 'no_data' parameter.
     # TODO(PyGMT>=0.19.0): Remove the following lines.
     with pytest.warns(FutureWarning):
-        result2 = grdfill(grid=grid_no_nan, constantfill=20, no_data=-99999)
+        result2 = grdfill(grid=grid_no_nan, constant_fill=20, no_data=-99999)
     xr.testing.assert_allclose(a=result2, b=expected_grid)
 
 
@@ -161,7 +161,7 @@ def test_grdfill_inquire_and_fill(grid):
     Test that grdfill fails if both inquire and fill parameters are given.
     """
     with pytest.raises(GMTInvalidInput):
-        grdfill(grid=grid, inquire=True, constantfill=20)
+        grdfill(grid=grid, inquire=True, constant_fill=20)
 
 
 # TODO(PyGMT>=0.19.0): Remove this test.