Figure.plot3d: Reorder input parameters to 'data, x, y, z' (#1560)

* Update plot3d.py
* adjust tests

Author: michaelgrund

pygmt/src/plot3d.py

@@ -5,6 +5,7 @@
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
     build_arg_string,
+    check_data_input_order,
     data_kind,
     deprecate_parameter,
     fmt_docstring,
@@ -18,6 +19,7 @@
 @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")
+@check_data_input_order("v0.5.0", remove_version="v0.7.0")
 @use_alias(
     A="straight_line",
     B="frame",
@@ -54,7 +56,7 @@
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
 def plot3d(
-    self, x=None, y=None, z=None, data=None, size=None, direction=None, **kwargs
+    self, data=None, x=None, y=None, z=None, size=None, direction=None, **kwargs
 ):
     r"""
     Plot lines, polygons, and symbols in 3-D.
@@ -83,13 +85,13 @@ def plot3d(
 
     Parameters
     ----------
-    x/y/z : float or 1d arrays
-        The x, y, and z coordinates, or arrays of x, y and z coordinates of
-        the data points
     data : str or {table-like}
         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.
+    x/y/z : float or 1d arrays
+        The x, y, and z coordinates, or arrays of x, y and z coordinates of
+        the data points
     size : 1d array
         The size of the data points in units specified in ``style``.
         Only valid if using ``x``/``y``/``z``.

pygmt/tests/test_plot3d.py

@@ -319,7 +319,7 @@ def test_plot3d_matrix(data, region):
     """
     fig = Figure()
     fig.plot3d(
-        data=data,
+        data,
         zscale=5,
         perspective=[225, 30],
         region=region,
@@ -343,7 +343,7 @@ def test_plot3d_matrix_color(data, region):
     """
     fig = Figure()
     fig.plot3d(
-        data=data,
+        data,
         zscale=5,
         perspective=[225, 30],
         region=region,
@@ -464,7 +464,7 @@ def test_plot3d_deprecate_columns_to_incols(data, region):
     fig = Figure()
     with pytest.warns(expected_warning=FutureWarning) as record:
         fig.plot3d(
-            data=data,
+            data,
             zscale=5,
             perspective=[225, 30],
             region=region,