Merge branch 'refactor/virtualfile_in' into refactor/validate_data_input

Author: seisman

pygmt/clib/session.py

@@ -1772,9 +1772,10 @@ def virtualfile_in(  # noqa: PLR0912
         x=None,
         y=None,
         z=None,
-        required_z=False,
         required_data=True,
+        ncols=2,
         extra_arrays=None,
+        required_z=False,
     ):
         """
         Store any data inside a virtual file.
@@ -1794,11 +1795,17 @@ def virtualfile_in(  # noqa: PLR0912
             data input.
         x/y/z : 1-D arrays or None
             x, y, and z columns as numpy arrays.
-        required_z : bool
-            State whether the 'z' column is required.
         required_data : bool
             Set to True when 'data' is required, or False when dealing with
             optional virtual files. [Default is True].
+        ncols
+            Number of minimum required columns.
+        required_z : bool
+            State whether the 'z' column is required.
+
+            .. deprecated:: v0.16.0
+               The parameter 'required_z' will be removed in v0.20.0. Use parameter
+               'ncols' instead. E.g., ``required_z=True`` is equivalent to ``ncols=3``.
         extra_arrays : list of 1-D arrays
             Optional. A list of numpy arrays in addition to x, y, and z. All of these
             arrays must be of the same size as the x/y/z arrays.
@@ -1833,6 +1840,17 @@ def virtualfile_in(  # noqa: PLR0912
         ...             print(fout.read().strip())
         <vector memory>: N = 3 <7/9> <4/6> <1/3>
         """
+        # TODO(PyGMT>=0.20.0): Remove the deprecated 'required_z' parameter.
+        if required_z is True:
+            warnings.warn(
+                "The parameter 'required_z' is deprecated and will be removed in "
+                "v0.20.0. Use parameter 'ncols' instead. E.g., ``required_z=True`` is "
+                "equivalent to ``ncols=3``.",
+                category=FutureWarning,
+                stacklevel=1,
+            )
+            ncols = 3
+
         # Specify either data or x/y/z.
         if data is not None and any(v is not None for v in (x, y, z)):
             msg = "Too much data. Use either data or x/y/z."
@@ -1912,7 +1930,7 @@ def virtualfile_in(  # noqa: PLR0912
                 _data = data.T
 
         # Check if _data to be passed to the virtualfile_from_ function is valid.
-        _validate_data_input(data=_data, kind=kind, required_z=required_z)
+        _validate_data_input(data=_data, kind=kind, ncols=ncols)
 
         # Finally create the virtualfile from the data, to be passed into GMT
         file_context = _virtualfile_from(_data)

pygmt/helpers/utils.py

@@ -45,7 +45,7 @@
 ]
 
 
-def _validate_data_input(data: Any, kind: Kind, required_z: bool = False) -> None:
+def _validate_data_input(data: Any, kind: Kind, ncols=2) -> None:
     """
     Check if the data to be passed to the virtualfile_from_ functions is valid.
 
@@ -67,7 +67,8 @@ def _validate_data_input(data: Any, kind: Kind, required_z: bool = False) -> Non
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Must provide both x and y.
-    >>> _validate_data_input(data=[[1, 2, 3], [4, 5, 6]], kind="empty", required_z=True)
+    >>> _validate_data_input(data=[[1, 2, 3], [4, 5, 6]], kind="empty", ncols=3)
+    >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], ncols=3)
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Must provide x, y, and z.
@@ -78,7 +79,7 @@ def _validate_data_input(data: Any, kind: Kind, required_z: bool = False) -> Non
     >>> import pandas as pd
     >>> import xarray as xr
     >>> data = np.arange(8).reshape((4, 2))
-    >>> _validate_data_input(data=data, kind="matrix", required_z=True)
+    >>> _validate_data_input(data=data, ncols=3, kind="matrix")
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Need at least 3 columns but 2 column(s) are given.
@@ -88,16 +89,16 @@ def _validate_data_input(data: Any, kind: Kind, required_z: bool = False) -> Non
 
     >>> _validate_data_input(
     ...     data=pd.DataFrame(data, columns=["x", "y"]),
+    ...     ncols=3,
     ...     kind="vectors",
-    ...     required_z=True,
     ... )
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Need at least 3 columns but 2 column(s) are given.
     >>> _validate_data_input(
     ...     data=xr.Dataset(pd.DataFrame(data, columns=["x", "y"])),
+    ...     ncols=3,
     ...     kind="vectors",
-    ...     required_z=True,
     ... )
     Traceback (most recent call last):
         ...
@@ -108,28 +109,25 @@ def _validate_data_input(data: Any, kind: Kind, required_z: bool = False) -> Non
     GMTInvalidInput
         If the data input is not valid.
     """
-    # Determine the required number of columns based on the required_z flag.
-    required_cols = 3 if required_z else 1
-
     match kind:
         case "empty":  # data = [x, y], [x, y, z], [x, y, z, ...]
             if len(data) < 2 or any(v is None for v in data[:2]):
                 msg = "Must provide both x and y."
                 raise GMTInvalidInput(msg)
-            if required_z and (len(data) < 3 or data[:3] is None):
+            if ncols >= 3 and (len(data) < 3 or data[:3] is None):
                 msg = "Must provide x, y, and z."
                 raise GMTInvalidInput(msg)
         case "matrix":  # 2-D numpy.ndarray
-            if (actual_cols := data.shape[1]) < required_cols:
-                msg = f"Need at least {required_cols} columns but {actual_cols} column(s) are given."
+            if (actual_cols := data.shape[1]) < ncols:
+                msg = f"Need at least {ncols} columns but {actual_cols} column(s) are given."
                 raise GMTInvalidInput(msg)
         case "vectors":
             # "vectors" means the original data is either dictionary, list, tuple,
             # pandas.DataFrame, pandas.Series, xarray.Dataset, or xarray.DataArray.
             # The original data is converted to a list of vectors or a 2-D numpy.ndarray
             # in the virtualfile_in function.
-            if (actual_cols := len(data)) < required_cols:
-                msg = f"Need at least {required_cols} columns but {actual_cols} column(s) are given."
+            if (actual_cols := len(data)) < ncols:
+                msg = f"Need at least {ncols} columns but {actual_cols} column(s) are given."
                 raise GMTInvalidInput(msg)
 
 

pygmt/src/blockm.py

@@ -55,7 +55,7 @@ def _blockm(
     with Session() as lib:
         with (
             lib.virtualfile_in(
-                check_kind="vector", data=data, x=x, y=y, z=z, required_z=True
+                check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
             ) as vintbl,
             lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl,
         ):

pygmt/src/contour.py

@@ -145,7 +145,7 @@ def contour(self, data=None, x=None, y=None, z=None, **kwargs):
 
     with Session() as lib:
         with lib.virtualfile_in(
-            check_kind="vector", data=data, x=x, y=y, z=z, required_z=True
+            check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
         ) as vintbl:
             lib.call_module(
                 module="contour", args=build_arg_list(kwargs, infile=vintbl)

pygmt/src/nearneighbor.py

@@ -141,7 +141,7 @@ def nearneighbor(
     with Session() as lib:
         with (
             lib.virtualfile_in(
-                check_kind="vector", data=data, x=x, y=y, z=z, required_z=True
+                check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
             ) as vintbl,
             lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
         ):

pygmt/src/plot3d.py

@@ -259,7 +259,5 @@ def plot3d(  # noqa: PLR0912
         kwargs["S"] = "u0.2c"
 
     with Session() as lib:
-        with lib.virtualfile_in(
-            check_kind="vector", data=data, required_z=True
-        ) as vintbl:
+        with lib.virtualfile_in(check_kind="vector", data=data, ncols=3) as vintbl:
             lib.call_module(module="plot3d", args=build_arg_list(kwargs, infile=vintbl))

pygmt/src/project.py

@@ -245,7 +245,7 @@ def project(
                 x=x,
                 y=y,
                 z=z,
-                required_z=False,
+                ncols=2,
                 required_data=False,
             ) as vintbl,
             lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl,

pygmt/src/surface.py

@@ -155,7 +155,7 @@ def surface(
     with Session() as lib:
         with (
             lib.virtualfile_in(
-                check_kind="vector", data=data, x=x, y=y, z=z, required_z=True
+                check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
             ) as vintbl,
             lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
         ):

pygmt/src/triangulate.py

@@ -138,7 +138,7 @@ def regular_grid(
         with Session() as lib:
             with (
                 lib.virtualfile_in(
-                    check_kind="vector", data=data, x=x, y=y, z=z, required_z=False
+                    check_kind="vector", data=data, x=x, y=y, z=z, ncols=2
                 ) as vintbl,
                 lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
             ):
@@ -238,7 +238,7 @@ def delaunay_triples(
         with Session() as lib:
             with (
                 lib.virtualfile_in(
-                    check_kind="vector", data=data, x=x, y=y, z=z, required_z=False
+                    check_kind="vector", data=data, x=x, y=y, z=z, ncols=2
                 ) as vintbl,
                 lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl,
             ):

pygmt/src/wiggle.py

@@ -108,6 +108,6 @@ def wiggle(
 
     with Session() as lib:
         with lib.virtualfile_in(
-            check_kind="vector", data=data, x=x, y=y, z=z, required_z=True
+            check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
         ) as vintbl:
             lib.call_module(module="wiggle", args=build_arg_list(kwargs, infile=vintbl))

pygmt/src/xyz2grd.py

@@ -149,7 +149,7 @@ def xyz2grd(
     with Session() as lib:
         with (
             lib.virtualfile_in(
-                check_kind="vector", data=data, x=x, y=y, z=z, required_z=True
+                check_kind="vector", data=data, x=x, y=y, z=z, ncols=3
             ) as vintbl,
             lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
         ):

pygmt/tests/test_clib_virtualfile_in.py

@@ -41,9 +41,7 @@ def test_virtualfile_in_required_z_matrix(array_func, kind):
     )
     data = array_func(dataframe)
     with clib.Session() as lib:
-        with lib.virtualfile_in(
-            data=data, required_z=True, check_kind="vector"
-        ) as vfile:
+        with lib.virtualfile_in(data=data, ncols=3, check_kind="vector") as vfile:
             with GMTTempFile() as outfile:
                 lib.call_module("info", [vfile, f"->{outfile.name}"])
                 output = outfile.read(keep_tabs=True)
@@ -64,10 +62,26 @@ def test_virtualfile_in_required_z_matrix_missing():
     data = np.ones((5, 2))
     with clib.Session() as lib:
         with pytest.raises(GMTInvalidInput):
-            with lib.virtualfile_in(data=data, required_z=True, check_kind="vector"):
+            with lib.virtualfile_in(data=data, ncols=3, check_kind="vector"):
                 pass
 
 
+# TODO(PyGMT>=0.20.0): Remove this test for the deprecated 'required_z' parameter.
+def test_virtualfile_in_required_z_deprecated():
+    """
+    Same as test_virtualfile_in_required_z_matrix_missing but using the deprecated
+    'required_z' parameter.
+    """
+    data = np.ones((5, 2))
+    with clib.Session() as lib:
+        with pytest.raises(GMTInvalidInput):  # noqa: PT012
+            with pytest.warns(FutureWarning):
+                with lib.virtualfile_in(
+                    data=data, required_z=True, check_kind="vector"
+                ):
+                    pass
+
+
 def test_virtualfile_in_fail_non_valid_data(data):
     """
     Should raise an exception if too few or too much data is given.
@@ -90,9 +104,7 @@ def test_virtualfile_in_fail_non_valid_data(data):
             continue
         with clib.Session() as lib:
             with pytest.raises(GMTInvalidInput):
-                lib.virtualfile_in(
-                    x=variable[0], y=variable[1], z=variable[2], required_z=True
-                )
+                lib.virtualfile_in(x=variable[0], y=variable[1], z=variable[2], ncols=3)
 
     # Should also fail if given too much data
     with clib.Session() as lib: