More fixes

Author: seisman

pygmt/clib/session.py

@@ -1765,7 +1765,7 @@ def virtualfile_from_stringio(
                     seg.header = None
                     seg.text = None
 
-    def virtualfile_in(
+    def virtualfile_in(  # noqa: PLR0912
         self,
         check_kind=None,
         data=None,
@@ -1829,7 +1829,7 @@ def virtualfile_in(
         ...             print(fout.read().strip())
         <vector memory>: N = 3 <7/9> <4/6> <1/3>
         """
-        # Check if the combination of data, and x/y/z is valid.
+        # 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."
             raise GMTInvalidInput(msg)
@@ -1846,7 +1846,7 @@ def virtualfile_in(
                 case "vector":
                     valid_kinds += ("empty", "matrix", "vectors", "geojson")
                 case _:
-                    msg = f"Unrecognized check_kind: {check_kind}."
+                    msg = f"Invalid value for check_kind: '{check_kind}'."
                     raise GMTInvalidInput(msg)
             if kind not in valid_kinds:
                 msg = f"Unrecognized data type for {check_kind}: {type(data)}."
@@ -1900,7 +1900,8 @@ def virtualfile_in(
                 _virtualfile_from = self.virtualfile_from_vectors
                 _data = data.T
 
-        _validate_data_input(data=_data, required_z=required_z, kind=kind)
+        # Check if _data to be passed to the virtualfile_from_ function is valid.
+        _validate_data_input(data=_data, kind=kind, required_z=required_z)
 
         # Finally create the virtualfile from the data, to be passed into GMT
         file_context = _virtualfile_from(_data)

pygmt/helpers/utils.py

@@ -47,70 +47,61 @@
 
 def _validate_data_input(data: Any, kind: Kind, required_z: bool = False) -> None:
     """
-    Check if the combination of data/x/y/z is valid.
+    Check if the data to be passed to the virtualfile_from_ functions is valid.
 
     Examples
     --------
-    >>> _validate_data_input(data="infile")
-    >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6])
-    >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], z=[7, 8, 9])
-    >>> _validate_data_input(data=None, required_data=False)
-    >>> _validate_data_input()
+    The "empty" kind means the data is given via a series of vectors like x/y/z.
+
+    >>> _validate_data_input(data=[[1, 2, 3], [4, 5, 6]], kind="empty")
+    >>> _validate_data_input(data=[[1, 2, 3], [4, 5, 6], [7, 8, 9]], kind="empty")
+    >>> _validate_data_input(data=[None, [4, 5, 6]], kind="empty")
     Traceback (most recent call last):
         ...
-    pygmt.exceptions.GMTInvalidInput: No input data provided.
-    >>> _validate_data_input(x=[1, 2, 3])
+    pygmt.exceptions.GMTInvalidInput: Must provide both x and y.
+    >>> _validate_data_input(data=[[1, 2, 3], None], kind="empty")
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Must provide both x and y.
-    >>> _validate_data_input(y=[4, 5, 6])
+    >>> _validate_data_input(data=[None, None], kind="empty")
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Must provide both x and y.
-    >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], required_z=True)
+    >>> _validate_data_input(data=[[1, 2, 3], [4, 5, 6]], kind="empty", required_z=True)
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Must provide x, y, and z.
+
+    The "matrix" kind means the data is given via a 2-D numpy.ndarray.
+
     >>> import numpy as np
     >>> import pandas as pd
     >>> import xarray as xr
     >>> data = np.arange(8).reshape((4, 2))
-    >>> _validate_data_input(data=data, required_z=True, kind="matrix")
+    >>> _validate_data_input(data=data, kind="matrix", required_z=True)
     Traceback (most recent call last):
         ...
     pygmt.exceptions.GMTInvalidInput: Need at least 3 columns but 2 column(s) are given.
+
+    The "vectors" kind means the original data is either dictionary, list, tuple,
+    pandas.DataFrame, pandas.Series, xarray.Dataset, or xarray.DataArray.
+
     >>> _validate_data_input(
     ...     data=pd.DataFrame(data, columns=["x", "y"]),
-    ...     required_z=True,
     ...     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"])),
-    ...     required_z=True,
     ...     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="infile", x=[1, 2, 3])
-    Traceback (most recent call last):
-        ...
-    pygmt.exceptions.GMTInvalidInput: Too much data. Use either data or x/y/z.
-    >>> _validate_data_input(data="infile", y=[4, 5, 6])
-    Traceback (most recent call last):
-        ...
-    pygmt.exceptions.GMTInvalidInput: Too much data. Use either data or x/y/z.
-    >>> _validate_data_input(data="infile", x=[1, 2, 3], y=[4, 5, 6])
-    Traceback (most recent call last):
-        ...
-    pygmt.exceptions.GMTInvalidInput: Too much data. Use either data or x/y/z.
-    >>> _validate_data_input(data="infile", z=[7, 8, 9])
-    Traceback (most recent call last):
-        ...
-    pygmt.exceptions.GMTInvalidInput: Too much data. Use either data or x/y/z.
 
     Raises
     ------
@@ -120,29 +111,25 @@ def _validate_data_input(data: Any, kind: Kind, required_z: bool = False) -> Non
     # Determine the required number of columns based on the required_z flag.
     required_cols = 3 if required_z else 1
 
-    # Check based on the data kind.
     match kind:
-        case "empty":  # data = [x, y, z]
-            if required_z and len(data) < 3:
-                msg = "Must provide x, y, and z."
-                raise GMTInvalidInput(msg)
-            if any(v is None for v in data):
+        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):
+                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."
-                )
+                msg = f"Need at least {required_cols} columns but {actual_cols} column(s) are given."
                 raise GMTInvalidInput(msg)
         case "vectors":
-            # Check if the number of columns is sufficient.
+            # "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."
-                )
+                msg = f"Need at least {required_cols} columns but {actual_cols} column(s) are given."
                 raise GMTInvalidInput(msg)