Merge branch 'main' into changelog/v0.12.0

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/helpers/decorators.py

@@ -630,10 +630,8 @@ def kwargs_to_strings(**conversions):
 
     Conversions available:
 
-    * 'sequence': transforms a sequence (list, tuple) into a ``'/'`` separated
-      string
-    * 'sequence_comma': transforms a sequence into a ``','`` separated string
-    * 'sequence_plus': transforms a sequence into a ``'+'`` separated string
+    * "sequence": transform a sequence (list, tuple) into a ``"/"`` separated string
+    * "sequence_comma": transform a sequence into a ``","`` separated string
 
     Parameters
     ----------
@@ -719,11 +717,7 @@ def kwargs_to_strings(**conversions):
     >>> module(["data1.txt", "data2.txt"], ("20p", "20p"), R=[1, 2, 3, 4])
     ['data1.txt', 'data2.txt'] 20p/20p {'R': '1/2/3/4'}
     """
-    separators = {
-        "sequence": "/",
-        "sequence_comma": ",",
-        "sequence_plus": "+",
-    }
+    separators = {"sequence": "/", "sequence_comma": ","}
 
     for arg, fmt in conversions.items():
         if fmt not in separators:

pygmt/src/contour.py

@@ -102,7 +102,16 @@ def contour(self, data=None, x=None, y=None, z=None, **kwargs):
     skip : bool or str
         [**p**\|\ **t**].
         Skip input points outside region.
-    {pen}
+    pen : str or list
+        [*type*]\ *pen*\ [**+c**\ [**l**\|\ **f**]].
+        *type*, if present, can be **a** for annotated contours or **c** for regular
+        contours [Default]. The pen sets the attributes for the particular line.
+        Default pen for annotated contours is ``"0.75p,black"`` and for regular
+        contours ``"0.25p,black"``. Normally, all contours are drawn with a fixed
+        color determined by the pen setting. If **+cl** is appended the colors of the
+        contour lines are taken from the CPT (see ``levels``). If **+cf** is
+        appended the colors from the CPT file are applied to the contour annotations.
+        Select **+c** for both effects.
     label : str
         Add a legend entry for the contour being plotted. Normally, the
         annotated contour is selected for the legend. You can select the

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.
@@ -86,7 +88,16 @@ def grdcontour(self, grid, **kwargs):
         five controlling algorithms. See :gmt-docs:`grdcontour.html#g` for
         details.
     {verbose}
-    {pen}
+    pen : str or list
+        [*type*]\ *pen*\ [**+c**\ [**l**\|\ **f**]].
+        *type*, if present, can be **a** for annotated contours or **c** for regular
+        contours [Default]. The pen sets the attributes for the particular line.
+        Default pen for annotated contours is ``"0.75p,black"`` and for regular
+        contours ``"0.25p,black"``. Normally, all contours are drawn with a fixed
+        color determined by the pen setting. If **+cl** is appended the colors of the
+        contour lines are taken from the CPT (see ``levels``). If **+cf** is
+        appended the colors from the CPT file are applied to the contour annotations.
+        Select **+c** for both effects.
     {panel}
     {coltypes}
     label : str
@@ -116,7 +127,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 +154,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",