Figure.grdview: Deprecate parameter drapegrid to drape_grid (Will be removed in v0.20.0) (#4276)

Author: yvonnefroehlich

examples/tutorials/advanced/draping_on_3d_surface.py

@@ -3,7 +3,7 @@
 ==================================================
 
 It can be visually appealing to "drape" a dataset over a topographic surface. This can
-be accomplished using the ``drapegrid`` parameter of :meth:`pygmt.Figure.grdview`.
+be accomplished using the ``drape_grid`` parameter of :meth:`pygmt.Figure.grdview`.
 
 This tutorial consists of two examples:
 
@@ -41,9 +41,9 @@
 # The topographic surface is created based on the grid passed to the ``grid`` parameter
 # of :meth:`pygmt.Figure.grdview`; here we use a grid of the Earth relief. To add a
 # color-coding based on *another* grid we have to pass a second grid to the
-# ``drapegrid`` parameter; here we use a grid of the crustal age. In this case the
+# ``drape_grid`` parameter; here we use a grid of the crustal age. In this case the
 # colormap specified via the ``cmap`` parameter applies to the grid passed to
-# ``drapegrid``, not to ``grid``. The azimuth and elevation of the 3-D plot are set via
+# ``drape_grid``, not to ``grid``. The azimuth and elevation of the 3-D plot are set via
 # the ``perspective`` parameter.
 
 fig = pygmt.Figure()
@@ -56,7 +56,7 @@
     projection="M12c",  # Mercator projection with a width of 12 centimeters
     region=region_3d,
     grid=grd_relief,  # Use elevation grid for z values
-    drapegrid=grd_age,  # Use crustal age grid for color-coding
+    drape_grid=grd_age,  # Use crustal age grid for color-coding
     cmap=True,  # Use colormap created for the crustal age
     surftype="i",  # Create an image plot
     # Use an illumination from the azimuthal directions 0° (north) and 270°
@@ -101,12 +101,12 @@
 url_to_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/b/b7/Flag_of_Europe.svg/1000px-Flag_of_Europe.svg.png"
 with rasterio.open(url_to_image) as dataset:
     data = dataset.read()
-    drapegrid = xr.DataArray(data, dims=("band", "y", "x"))
+    drape_grid = xr.DataArray(data, dims=("band", "y", "x"))
 
 # %%
 # Again we create a 3-D plot with :meth:`pygmt.Figure.grdview` and pass an Earth relief
 # grid to the ``grid`` parameter to create the topographic surface. But now we pass the
-# PNG image which was loaded into an :class:`xarray.DataArray` to the ``drapgrid``
+# PNG image which was loaded into an :class:`xarray.DataArray` to the ``drape_grid``
 # parameter.
 
 fig = pygmt.Figure()
@@ -120,7 +120,7 @@
     projection="M12c",  # Mercator projection with a width of 12 centimeters
     region=region_3d,
     grid=grd_relief,  # Use elevation grid for z values
-    drapegrid=drapegrid,  # Drap image grid for the EU flag on top
+    drape_grid=drape_grid,  # Drape image grid for the EU flag on top
     cmap=True,  # Use colormap defined for the EU flag
     surftype="i",  # Create an image plot
     # Use an illumination from the azimuthal directions 0° (north) and 270° (west) with

pygmt/src/grdview.py

@@ -18,9 +18,10 @@
 @deprecate_parameter("contourpen", "contour_pen", "v0.18.0", remove_version="v0.20.0")
 @deprecate_parameter("facadepen", "facade_pen", "v0.18.0", remove_version="v0.20.0")
 @deprecate_parameter("meshpen", "mesh_pen", "v0.18.0", remove_version="v0.20.0")
+@deprecate_parameter("drapegrid", "drape_grid", "v0.18.0", remove_version="v0.20.0")
 @use_alias(
     C="cmap",
-    G="drapegrid",
+    G="drape_grid",
     Q="surftype",
     I="shading",
     f="coltypes",
@@ -86,11 +87,11 @@ def grdview(  # noqa: PLR0913
     $frame
     cmap : str
         The name of the color palette table to use.
-    drapegrid : str or :class:`xarray.DataArray`
+    drape_grid : str or :class:`xarray.DataArray`
         The file name or a :class:`xarray.DataArray` of the image grid to be draped on
         top of the relief provided by ``grid`` [Default determines colors from ``grid``]
-        Note that ``zscale`` and ``plane`` always refer to ``grid``. ``drapegrid`` only
-        provides the information pertaining to colors, which (if ``drapegrid`` is a
+        Note that ``zscale`` and ``plane`` always refer to ``grid``. ``drape_grid`` only
+        provides the information pertaining to colors, which (if ``drape_grid`` is a
         grid) will be looked-up via the CPT (see ``cmap``).
     surftype : str
         Specify cover type of the grid. Select one of following settings:

pygmt/tests/test_grdview.py

@@ -232,27 +232,27 @@ def test_grdview_facadepen_default_plane(xrgrid):
 @pytest.mark.mpl_image_compare
 def test_grdview_drapegrid_dataarray(xrgrid):
     """
-    Run grdview by passing in both a grid and drapegrid as an xarray.DataArray, setting
+    Run grdview by passing in both a grid and drape_grid as an xarray.DataArray, setting
     a colormap for producing an image plot.
     """
-    drapegrid = 1.1 * xrgrid
+    drape_grid = 1.1 * xrgrid
 
     # accessor information are lost during xarray multiplication
-    drapegrid.gmt.registration = xrgrid.gmt.registration
-    drapegrid.gmt.gtype = xrgrid.gmt.gtype
+    drape_grid.gmt.registration = xrgrid.gmt.registration
+    drape_grid.gmt.gtype = xrgrid.gmt.gtype
 
     fig = Figure()
     fig.grdview(
-        grid=xrgrid, drapegrid=drapegrid, cmap="oleron", surftype="c", frame=True
+        grid=xrgrid, drape_grid=drape_grid, cmap="oleron", surftype="c", frame=True
     )
     return fig
 
 
 def test_grdview_wrong_kind_of_drapegrid(xrgrid):
     """
-    Run grdview using drapegrid input that is not an xarray.DataArray or file.
+    Run grdview using drape_grid input that is not an xarray.DataArray or file.
     """
     dataset = xrgrid.to_dataset()  # convert xarray.DataArray to xarray.Dataset
     fig = Figure()
     with pytest.raises(GMTTypeError):
-        fig.grdview(grid=xrgrid, drapegrid=dataset)
+        fig.grdview(grid=xrgrid, drape_grid=dataset)