Figure.plot3d: Deprecate parameter "columns" to "incols" (remove in v0.6.0) (#1040)

* Add "incols" parameter in plot3d.py
* change data accepted types to include table-like
* add @deprecate_parameter for columns parameter
* add test for deprecated "columns" parameter in plot3d

Co-authored-by: Meghan Jones <meghanj@hawaii.edu>
Co-authored-by: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Author: 4 people

pygmt/src/plot3d.py

@@ -15,6 +15,8 @@
 
 
 @fmt_docstring
+@deprecate_parameter("columns", "incols", "v0.4.0", remove_version="v0.6.0")
+@deprecate_parameter("sizes", "size", "v0.4.0", remove_version="v0.6.0")
 @use_alias(
     A="straight_line",
     B="frame",
@@ -36,15 +38,14 @@
     Y="yshift",
     Z="zvalue",
     a="aspatial",
-    i="columns",
+    i="incols",
     l="label",
     c="panel",
     f="coltypes",
     p="perspective",
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
-@deprecate_parameter("sizes", "size", "v0.4.0", remove_version="v0.6.0")
 def plot3d(
     self, x=None, y=None, z=None, data=None, size=None, direction=None, **kwargs
 ):
@@ -79,10 +80,9 @@ def plot3d(
         The x, y, and z coordinates, or arrays of x, y and z coordinates of
         the data points
     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, color,
-        and size, respectively.
+        Either a data file name, a 2d {table-classes}.
+        Optionally, use parameter ``incols`` to specify which columns are x, y,
+        z, color, and size, respectively.
     size : 1d array
         The size of the data points in units specified in ``style``.
         Only valid if using ``x``/``y``/``z``.
@@ -163,6 +163,7 @@ def plot3d(
     {a}
     {c}
     {f}
+    {i}
     label : str
         Add a legend entry for the symbol or line being plotted.
     {p}

pygmt/tests/test_plot3d.py

@@ -356,7 +356,7 @@ def test_plot3d_sizes_colors_transparencies():
 @pytest.mark.mpl_image_compare
 def test_plot3d_matrix(data, region):
     """
-    Plot the data passing in a matrix and specifying columns.
+    Plot the data passing in a matrix and specifying incols.
     """
     fig = Figure()
     fig.plot3d(
@@ -368,7 +368,7 @@ def test_plot3d_matrix(data, region):
         style="c1c",
         color="#aaaaaa",
         frame=["a", "za"],
-        columns="0,1,2",
+        incols="0,1,2",
     )
     return fig
 
@@ -391,7 +391,7 @@ def test_plot3d_matrix_color(data, region):
         projection="X10c",
         style="c0.5c",
         cmap="rainbow",
-        columns=[0, 1, 2, 2],
+        incols=[0, 1, 2, 2],
         frame=["a", "za"],
     )
     return fig
@@ -412,7 +412,7 @@ def test_plot3d_from_file(region):
         style="d1c",
         color="yellow",
         frame=["af", "zaf"],
-        columns=[0, 1, 2],
+        incols=[0, 1, 2],
     )
     return fig
 
@@ -492,3 +492,28 @@ def test_plot3d_deprecate_sizes_to_size(data, region):
         )
         assert len(record) == 1  # check that only one warning was raised
     return fig
+
+
+@pytest.mark.mpl_image_compare(filename="test_plot3d_matrix.png")
+def test_plot3d_deprecate_columns_to_incols(data, region):
+    """
+    Make sure that the old parameter "columns" is supported and it reports an
+    warning.
+
+    Modified from the test_plot3d_matrix() test.
+    """
+    fig = Figure()
+    with pytest.warns(expected_warning=FutureWarning) as record:
+        fig.plot3d(
+            data=data,
+            zscale=5,
+            perspective=[225, 30],
+            region=region,
+            projection="M20c",
+            style="c1c",
+            color="#aaaaaa",
+            frame=["a", "za"],
+            columns="0,1,2",
+        )
+        assert len(record) == 1  # check that only one warning was raised
+    return fig