Figure.wiggle: Deprecate parameter "columns" to "incols" (remove in v…

…0.7.0) (GenericMappingTools#1504)

pygmt/src/wiggle.py

@@ -2,10 +2,17 @@
 wiggle - Plot z=f(x,y) anomalies along tracks.
 """
 from pygmt.clib import Session
-from pygmt.helpers import build_arg_string, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.helpers import (
+    build_arg_string,
+    deprecate_parameter,
+    fmt_docstring,
+    kwargs_to_strings,
+    use_alias,
+)
 
 
 @fmt_docstring
+@deprecate_parameter("columns", "incols", "v0.5.0", remove_version="v0.7.0")
 @use_alias(
     B="frame",
     D="position",
@@ -25,7 +32,7 @@
     e="find",
     g="gap",
     h="header",
-    i="columns",
+    i="incols",
     p="perspective",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
@@ -49,7 +56,7 @@ def wiggle(self, x=None, y=None, z=None, data=None, **kwargs):
     data : str or {table-like}
         Pass in either a file name to an ASCII data table, a 2D
         {table-classes}.
-        Use parameter ``columns`` to choose which columns are x, y, z,
+        Use parameter ``incols`` to choose which columns are x, y, z,
         respectively.
     {J}
     {R}
@@ -86,11 +93,7 @@ def wiggle(self, x=None, y=None, z=None, data=None, **kwargs):
     {e}
     {g}
     {h}
-    columns : str or 1d array
-        Choose which columns are x, y, and z, respectively if input is provided
-        via *data*. E.g. ``columns = [0, 1, 2]`` or ``columns = "0,1,2"`` if
-        the *x* values are stored in the first column, *y* values in the second
-        one and *z* values in the third one. Note: zero-based indexing is used.
+    {i}
     {p}
     """
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access

pygmt/tests/test_wiggle.py

@@ -29,3 +29,36 @@ def test_wiggle():
         position="jRM+w2+lnT",
     )
     return fig
+
+
+@pytest.mark.mpl_image_compare(filename="test_wiggle.png")
+def test_wiggle_deprecate_columns_to_incols():
+    """
+    Make sure that the old parameter "columns" is supported and it reports a
+    warning.
+
+    Modified from the test_wiggle() test.
+    """
+
+    # put data into numpy array and swap x and y columns
+    # as the use of the 'columns' parameter will reverse this action
+    x = np.arange(-2, 2, 0.02)
+    y = np.zeros(x.size)
+    z = np.cos(2 * np.pi * x)
+    data = np.array([y, x, z]).T
+
+    fig = Figure()
+    with pytest.warns(expected_warning=FutureWarning) as record:
+        fig.wiggle(
+            region=[-4, 4, -1, 1],
+            projection="X8c",
+            data=data,
+            columns=[1, 0, 2],
+            scale="0.5c",
+            color=["red+p", "gray+n"],
+            pen="1.0p",
+            track="0.5p",
+            position="jRM+w2+lnT",
+        )
+        assert len(record) == 1  # check that only one warning was raised
+    return fig