Figure.grdcontour: Deprecate parameter "interval" to "levels" (FutureWarning since v0.12.0, will be removed in v0.16.0) (#3209)

Author: yvonnefroehlich

examples/get_started/02_contour_map.py

@@ -82,7 +82,7 @@
 # :meth:`pygmt.Figure.grdcontour` method is used. The ``frame`` and
 # ``projection`` are already set using :meth:`pygmt.Figure.grdimage` and are
 # not needed again. However, the same input for ``grid`` (in this case, the
-# variable named "grid") must be input again. The ``interval`` parameter sets
+# variable named "grid") must be input again. The ``levels`` parameter sets
 # the spacing between adjacent contour lines (in this case, 500 meters). The
 # ``annotation`` parameter annotates the contour lines corresponding to the
 # given interval (in this case, 1,000 meters) with the related values, here
@@ -93,7 +93,7 @@
 
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, frame="a", projection="M10c", cmap="oleron")
-fig.grdcontour(grid=grid, interval=500, annotation=1000)
+fig.grdcontour(grid=grid, levels=500, annotation=1000)
 fig.colorbar(frame=["a1000", "x+lElevation", "y+lm"])
 fig.show()
 
@@ -109,7 +109,7 @@
 
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, frame="a", projection="M10c", cmap="oleron")
-fig.grdcontour(grid=grid, interval=500, annotation=1000)
+fig.grdcontour(grid=grid, levels=500, annotation=1000)
 fig.coast(shorelines="2p", land="lightgray")
 fig.colorbar(frame=["a1000", "x+lElevation", "y+lm"])
 fig.show()

examples/tutorials/advanced/contour_map.py

@@ -33,16 +33,12 @@
 # Contour line settings
 # ---------------------
 #
-# Use the ``annotation`` and ``interval`` parameters to adjust contour line
+# Use the ``annotation`` and ``levels`` parameters to adjust contour line
 # intervals. In the example below, there are contour intervals every 250 meters
 # and annotated contour lines every 1,000 meters.
 
 fig = pygmt.Figure()
-fig.grdcontour(
-    annotation=1000,
-    interval=250,
-    grid=grid,
-)
+fig.grdcontour(annotation=1000, levels=250, grid=grid)
 fig.show()
 
 
@@ -57,7 +53,7 @@
 fig = pygmt.Figure()
 fig.grdcontour(
     annotation=1000,
-    interval=250,
+    levels=250,
     grid=grid,
     limit=[-4000, -2000],
 )
@@ -74,7 +70,7 @@
 fig = pygmt.Figure()
 fig.grdcontour(
     annotation=1000,
-    interval=250,
+    levels=250,
     grid=grid,
     limit=[-4000, -2000],
     projection="M10c",
@@ -104,7 +100,7 @@
 )
 fig.grdcontour(
     annotation=1000,
-    interval=250,
+    levels=250,
     grid=grid,
     limit=[-4000, -2000],
 )

pygmt/src/grdcontour.py

@@ -7,6 +7,7 @@
 from pygmt.clib import Session
 from pygmt.helpers import (
     build_arg_list,
+    deprecate_parameter,
     fmt_docstring,
     is_nonstr_iter,
     kwargs_to_strings,
@@ -17,10 +18,11 @@
 
 
 @fmt_docstring
+@deprecate_parameter("interval", "levels", "v0.12.0", remove_version="v0.16.0")
 @use_alias(
     A="annotation",
     B="frame",
-    C="interval",
+    C="levels",
     G="label_placement",
     J="projection",
     L="limit",
@@ -49,7 +51,7 @@ def grdcontour(self, grid, **kwargs):
     Parameters
     ----------
     {grid}
-    interval : float, list, or str
+    levels : float, list, or str
         Specify the contour lines to generate.
 
         - The file name of a CPT file where the color boundaries will be used as
@@ -60,7 +62,7 @@ def grdcontour(self, grid, **kwargs):
         - A list of contour levels.
     annotation : float, list, or str
         Specify or disable annotated contour levels, modifies annotated
-        contours specified in ``interval``.
+        contours specified in ``levels``.
 
         - Specify a fixed annotation interval.
         - Specify a list of annotation levels.
@@ -116,7 +118,7 @@ def grdcontour(self, grid, **kwargs):
     ...     # Pass in the grid downloaded above
     ...     grid=grid,
     ...     # Set the interval for contour lines at 250 meters
-    ...     interval=250,
+    ...     levels=250,
     ...     # Set the interval for annotated contour lines at 1,000 meters
     ...     annotation=1000,
     ...     # Add a frame for the plot
@@ -143,7 +145,7 @@ def grdcontour(self, grid, **kwargs):
         warnings.warn(msg, category=FutureWarning, stacklevel=2)
         kwargs["A"] = "+".join(f"{item}" for item in kwargs["A"])
 
-    # Specify levels for the annotation and interval parameters.
+    # Specify levels for the annotation and levels parameters.
     # One level is converted to a string with a trailing comma to separate it from
     # specifying an interval.
     # Multiple levels are concatenated to a comma-separated string.

pygmt/tests/test_grdcontour.py

@@ -28,9 +28,7 @@ def test_grdcontour(grid):
     annotation intervals.
     """
     fig = Figure()
-    fig.grdcontour(
-        grid=grid, interval=50, annotation=200, projection="M10c", frame=True
-    )
+    fig.grdcontour(grid=grid, levels=50, annotation=200, projection="M10c", frame=True)
     return fig
 
 
@@ -42,7 +40,7 @@ def test_grdcontour_one_level(grid):
     """
     fig = Figure()
     fig.grdcontour(
-        grid=grid, interval=[400], annotation=[570], projection="M10c", frame=True
+        grid=grid, levels=[400], annotation=[570], projection="M10c", frame=True
     )
     return fig
 
@@ -56,7 +54,7 @@ def test_grdcontour_old_annotations(grid):
     fig = Figure()
     fig.grdcontour(
         grid=grid,
-        interval=[400],
+        levels=[400],
         annotation=["570,", "gwhite"],
         projection="M10c",
         frame=True,
@@ -73,7 +71,7 @@ def test_grdcontour_multiple_levels(grid):
     fig = Figure()
     fig.grdcontour(
         grid=grid,
-        interval=[400, 450, 500],
+        levels=[400, 450, 500],
         annotation=[400, 570],
         projection="M10c",
         frame=True,
@@ -90,7 +88,7 @@ def test_grdcontour_labels(grid):
     fig = Figure()
     fig.grdcontour(
         grid=grid,
-        interval=50,
+        levels=50,
         annotation=200,
         projection="M10c",
         pen=["a1p,red", "c0.5p,black"],
@@ -108,7 +106,7 @@ def test_grdcontour_slice(grid):
     grid_ = grid.sel(lat=slice(-20, -10))
 
     fig = Figure()
-    fig.grdcontour(grid=grid_, interval=100, projection="M10c", frame=True)
+    fig.grdcontour(grid=grid_, levels=100, projection="M10c", frame=True)
     return fig
 
 
@@ -121,7 +119,7 @@ def test_grdcontour_interval_file_full_opts(grid):
 
     comargs = {
         "region": [-53, -49, -20, -17],
-        "interval": TEST_CONTOUR_FILE,
+        "levels": TEST_CONTOUR_FILE,
         "grid": grid,
         "resample": 100,
         "projection": "M10c",