From 10a7333ccd19c3e57252ac33a6f8bd982c7c5739 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 2 Oct 2024 19:23:20 +0800
Subject: [PATCH 1/6] data_kind: Add more tests to demonstrate the data kind of
 various data types

---
 pygmt/helpers/utils.py           | 74 +++++++++++++++++++++++++-------
 pygmt/tests/test_blockm.py       |  3 +-
 pygmt/tests/test_blockmedian.py  |  3 +-
 pygmt/tests/test_geopandas.py    | 16 +++++++
 pygmt/tests/test_grdtrack.py     |  6 +--
 pygmt/tests/test_grdview.py      |  6 +--
 pygmt/tests/test_nearneighbor.py |  3 +-
 pygmt/tests/test_surface.py      |  3 +-
 pygmt/tests/test_triangulate.py  |  3 +-
 pygmt/tests/test_x2sys_cross.py  |  2 -
 10 files changed, 81 insertions(+), 38 deletions(-)

diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py
index 6585bb7566b..bab948553f2 100644
--- a/pygmt/helpers/utils.py
+++ b/pygmt/helpers/utils.py
@@ -222,30 +222,72 @@ def data_kind(
 
     Examples
     --------
+    >>> import io
+    >>> from pathlib import Path
     >>> import numpy as np
+    >>> import pandas as pd
     >>> import xarray as xr
-    >>> import pathlib
-    >>> import io
-    >>> data_kind(data=None)
-    'vectors'
-    >>> data_kind(data=np.arange(10).reshape((5, 2)))
-    'matrix'
-    >>> data_kind(data="my-data-file.txt")
-    'file'
-    >>> data_kind(data=pathlib.Path("my-data-file.txt"))
-    'file'
+
+    The "arg" kind:
+
+    >>> [data_kind(data=data, required=False) for data in (2, 2.0, True, False)]
+    ['arg', 'arg', 'arg', 'arg']
     >>> data_kind(data=None, required=False)
     'arg'
-    >>> data_kind(data=2.0, required=False)
-    'arg'
-    >>> data_kind(data=True, required=False)
-    'arg'
-    >>> data_kind(data=xr.DataArray(np.random.rand(4, 3)))
+
+    The "file" kind:
+
+    >>> [data_kind(data=data) for data in ("file.txt", ("file1.txt", "file2.txt"))]
+    ['file', 'file']
+    >>> data_kind(data=Path("file.txt"))
+    'file'
+    >>> data_kind(data=(Path("file1.txt", "file2.txt")))
+    'file'
+
+    The "grid" kind:
+
+    >>> data_kind(data=xr.DataArray(np.random.rand(4, 3)))  # 2-D xarray.DataArray
+    'grid'
+    >>> data_kind(data=xr.DataArray(np.arange(12)))  # 1-D xarray.DataArray
+    'grid'
+    >>> data_kind(data=xr.DataArray(np.random.rand(2, 3, 4, 5)))  # 4-D xarray.DataArray
     'grid'
-    >>> data_kind(data=xr.DataArray(np.random.rand(3, 4, 5)))
+
+    The "image" kind:
+
+    >>> data_kind(data=xr.DataArray(np.random.rand(3, 4, 5)))  # 3-D xarray.DataArray
     'image'
+
+    The "stringio"`` kind:
+
     >>> data_kind(data=io.StringIO("TEXT1\nTEXT23\n"))
     'stringio'
+
+    The "matrix"`` kind:
+
+    >>> data_kind(data=np.arange(10))  # 1-D numpy.ndarray
+    'matrix'
+    >>> data_kind(data=np.arange(10).reshape((5, 2)))  # 2-D numpy.ndarray
+    'matrix'
+    >>> data_kind(data=np.arange(60).reshape((3, 4, 5)))  # 3-D numpy.ndarray
+    'matrix'
+    >>> data_kind(xr.DataArray(np.arange(12), name="x").to_dataset())  # xarray.Dataset
+    'matrix'
+    >>> data_kind(data=[1, 2, 3])  # 1-D sequence
+    'matrix'
+    >>> data_kind(data=[[1, 2, 3], [4, 5, 6]])  # sequence of sequences
+    'matrix'
+    >>> data_kind(data={"x": [1, 2, 3], "y": [4, 5, 6]})
+    'matrix'
+    >>> data_kind(data=pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]}))  # pd.DataFrame
+    'matrix'
+    >>> data_kind(data=pd.Series([1, 2, 3], name="x"))  # pd.Series
+    'matrix'
+
+    The "vectors" kind:
+
+    >>> data_kind(data=None)
+    'vectors'
     """
     kind: Literal[
         "arg", "file", "geojson", "grid", "image", "matrix", "stringio", "vectors"
diff --git a/pygmt/tests/test_blockm.py b/pygmt/tests/test_blockm.py
index b9f656e99ea..a0e2ee49d4e 100644
--- a/pygmt/tests/test_blockm.py
+++ b/pygmt/tests/test_blockm.py
@@ -12,7 +12,7 @@
 from pygmt import blockmean, blockmode
 from pygmt.datasets import load_sample_data
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import GMTTempFile, data_kind
+from pygmt.helpers import GMTTempFile
 
 
 @pytest.fixture(scope="module", name="dataframe")
@@ -68,7 +68,6 @@ def test_blockmean_wrong_kind_of_input_table_grid(dataframe):
     Run blockmean using table input that is not a pandas.DataFrame or file but a grid.
     """
     invalid_table = dataframe.bathymetry.to_xarray()
-    assert data_kind(invalid_table) == "grid"
     with pytest.raises(GMTInvalidInput):
         blockmean(data=invalid_table, spacing="5m", region=[245, 255, 20, 30])
 
diff --git a/pygmt/tests/test_blockmedian.py b/pygmt/tests/test_blockmedian.py
index 6f3f24b3c77..64d642f424d 100644
--- a/pygmt/tests/test_blockmedian.py
+++ b/pygmt/tests/test_blockmedian.py
@@ -10,7 +10,7 @@
 from pygmt import blockmedian
 from pygmt.datasets import load_sample_data
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import GMTTempFile, data_kind
+from pygmt.helpers import GMTTempFile
 
 
 @pytest.fixture(scope="module", name="dataframe")
@@ -65,7 +65,6 @@ def test_blockmedian_wrong_kind_of_input_table_grid(dataframe):
     Run blockmedian using table input that is not a pandas.DataFrame or file but a grid.
     """
     invalid_table = dataframe.bathymetry.to_xarray()
-    assert data_kind(invalid_table) == "grid"
     with pytest.raises(GMTInvalidInput):
         blockmedian(data=invalid_table, spacing="5m", region=[245, 255, 20, 30])
 
diff --git a/pygmt/tests/test_geopandas.py b/pygmt/tests/test_geopandas.py
index 77fa7a9f9d5..336a076d64c 100644
--- a/pygmt/tests/test_geopandas.py
+++ b/pygmt/tests/test_geopandas.py
@@ -6,6 +6,7 @@
 import pandas as pd
 import pytest
 from pygmt import Figure, info, makecpt, which
+from pygmt.helpers import data_kind
 from pygmt.helpers.testing import skip_if_no
 
 gpd = pytest.importorskip("geopandas")
@@ -243,3 +244,18 @@ def test_geopandas_plot_int64_as_float(gdf_ridge):
     makecpt(cmap="lisbon", series=[10, 60, 10], continuous=True)
     fig.colorbar()
     return fig
+
+
+def test_geopandas_data_kind_geopandas(gdf):
+    """
+    Check if geopandas.GeoDataFrame object is recognized as a "geojson" kind.
+    """
+    assert data_kind(data=gdf) == "geojson"
+
+
+def test_geopandas_data_kind_shapely():
+    """
+    Check if shapely.geometry object is recognized as a "geojson" kind.
+    """
+    polygon = shapely.geometry.Polygon([(20, 10), (23, 10), (23, 14), (20, 14)])
+    assert data_kind(data=polygon) == "geojson"
diff --git a/pygmt/tests/test_grdtrack.py b/pygmt/tests/test_grdtrack.py
index f3862adeae0..4088da01ac8 100644
--- a/pygmt/tests/test_grdtrack.py
+++ b/pygmt/tests/test_grdtrack.py
@@ -10,7 +10,7 @@
 import pytest
 from pygmt import grdtrack
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import GMTTempFile, data_kind
+from pygmt.helpers import GMTTempFile
 from pygmt.helpers.testing import load_static_earth_relief
 
 POINTS_DATA = Path(__file__).parent / "data" / "track.txt"
@@ -129,8 +129,6 @@ def test_grdtrack_wrong_kind_of_points_input(dataarray, dataframe):
     Run grdtrack using points input that is not a pandas.DataFrame (matrix) or file.
     """
     invalid_points = dataframe.longitude.to_xarray()
-
-    assert data_kind(invalid_points) == "grid"
     with pytest.raises(GMTInvalidInput):
         grdtrack(points=invalid_points, grid=dataarray, newcolname="bathymetry")
 
@@ -140,8 +138,6 @@ def test_grdtrack_wrong_kind_of_grid_input(dataarray, dataframe):
     Run grdtrack using grid input that is not as xarray.DataArray (grid) or file.
     """
     invalid_grid = dataarray.to_dataset()
-
-    assert data_kind(invalid_grid) == "matrix"
     with pytest.raises(GMTInvalidInput):
         grdtrack(points=dataframe, grid=invalid_grid, newcolname="bathymetry")
 
diff --git a/pygmt/tests/test_grdview.py b/pygmt/tests/test_grdview.py
index b8f597b2bf0..f73b1150e54 100644
--- a/pygmt/tests/test_grdview.py
+++ b/pygmt/tests/test_grdview.py
@@ -5,7 +5,7 @@
 import pytest
 from pygmt import Figure, grdcut
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import GMTTempFile, data_kind
+from pygmt.helpers import GMTTempFile
 from pygmt.helpers.testing import load_static_earth_relief
 
 
@@ -58,8 +58,6 @@ def test_grdview_wrong_kind_of_grid(xrgrid):
     Run grdview using grid input that is not an xarray.DataArray or file.
     """
     dataset = xrgrid.to_dataset()  # convert xarray.DataArray to xarray.Dataset
-    assert data_kind(dataset) == "matrix"
-
     fig = Figure()
     with pytest.raises(GMTInvalidInput):
         fig.grdview(grid=dataset)
@@ -238,8 +236,6 @@ def test_grdview_wrong_kind_of_drapegrid(xrgrid):
     Run grdview using drapegrid input that is not an xarray.DataArray or file.
     """
     dataset = xrgrid.to_dataset()  # convert xarray.DataArray to xarray.Dataset
-    assert data_kind(dataset) == "matrix"
-
     fig = Figure()
     with pytest.raises(GMTInvalidInput):
         fig.grdview(grid=xrgrid, drapegrid=dataset)
diff --git a/pygmt/tests/test_nearneighbor.py b/pygmt/tests/test_nearneighbor.py
index f37365fbdb4..9d08aa0e8d1 100644
--- a/pygmt/tests/test_nearneighbor.py
+++ b/pygmt/tests/test_nearneighbor.py
@@ -11,7 +11,7 @@
 from pygmt import nearneighbor
 from pygmt.datasets import load_sample_data
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import GMTTempFile, data_kind
+from pygmt.helpers import GMTTempFile
 
 
 @pytest.fixture(scope="module", name="ship_data")
@@ -61,7 +61,6 @@ def test_nearneighbor_wrong_kind_of_input(ship_data):
     Run nearneighbor using grid input that is not file/matrix/vectors.
     """
     data = ship_data.bathymetry.to_xarray()  # convert pandas.Series to xarray.DataArray
-    assert data_kind(data) == "grid"
     with pytest.raises(GMTInvalidInput):
         nearneighbor(
             data=data, spacing="5m", region=[245, 255, 20, 30], search_radius="10m"
diff --git a/pygmt/tests/test_surface.py b/pygmt/tests/test_surface.py
index 39860dd2069..e8ec0cf3445 100644
--- a/pygmt/tests/test_surface.py
+++ b/pygmt/tests/test_surface.py
@@ -9,7 +9,7 @@
 import xarray as xr
 from pygmt import surface, which
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import GMTTempFile, data_kind
+from pygmt.helpers import GMTTempFile
 
 
 @pytest.fixture(scope="module", name="data")
@@ -125,7 +125,6 @@ def test_surface_wrong_kind_of_input(data, region, spacing):
     Run surface using grid input that is not file/matrix/vectors.
     """
     data = data.z.to_xarray()  # convert pandas.Series to xarray.DataArray
-    assert data_kind(data) == "grid"
     with pytest.raises(GMTInvalidInput):
         surface(data=data, spacing=spacing, region=region)
 
diff --git a/pygmt/tests/test_triangulate.py b/pygmt/tests/test_triangulate.py
index 75cccbf17ab..97c29a273e6 100644
--- a/pygmt/tests/test_triangulate.py
+++ b/pygmt/tests/test_triangulate.py
@@ -10,7 +10,7 @@
 import xarray as xr
 from pygmt import triangulate, which
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import GMTTempFile, data_kind
+from pygmt.helpers import GMTTempFile
 
 
 @pytest.fixture(scope="module", name="dataframe")
@@ -93,7 +93,6 @@ def test_delaunay_triples_wrong_kind_of_input(dataframe):
     Run triangulate.delaunay_triples using grid input that is not file/matrix/vectors.
     """
     data = dataframe.z.to_xarray()  # convert pandas.Series to xarray.DataArray
-    assert data_kind(data) == "grid"
     with pytest.raises(GMTInvalidInput):
         triangulate.delaunay_triples(data=data)
 
diff --git a/pygmt/tests/test_x2sys_cross.py b/pygmt/tests/test_x2sys_cross.py
index eba29aa6242..00be06173a6 100644
--- a/pygmt/tests/test_x2sys_cross.py
+++ b/pygmt/tests/test_x2sys_cross.py
@@ -16,7 +16,6 @@
 from pygmt.clib import __gmt_version__
 from pygmt.datasets import load_sample_data
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.helpers import data_kind
 
 
 @pytest.fixture(name="mock_x2sys_home")
@@ -241,7 +240,6 @@ def test_x2sys_cross_invalid_tracks_input_type(tracks):
     (file) type, which would raise a GMTInvalidInput error.
     """
     invalid_tracks = tracks[0].to_xarray().z
-    assert data_kind(invalid_tracks) == "grid"
     with pytest.raises(GMTInvalidInput):
         x2sys_cross(tracks=[invalid_tracks])
 

From 4cf80a922a439e5124f5d608b47ee6a1687e55f8 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 2 Oct 2024 20:42:18 +0800
Subject: [PATCH 2/6] Update pygmt/helpers/utils.py

---
 pygmt/helpers/utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py
index bab948553f2..6140960ff38 100644
--- a/pygmt/helpers/utils.py
+++ b/pygmt/helpers/utils.py
@@ -277,7 +277,7 @@ def data_kind(
     'matrix'
     >>> data_kind(data=[[1, 2, 3], [4, 5, 6]])  # sequence of sequences
     'matrix'
-    >>> data_kind(data={"x": [1, 2, 3], "y": [4, 5, 6]})
+    >>> data_kind(data={"x": [1, 2, 3], "y": [4, 5, 6]})  # dictionary
     'matrix'
     >>> data_kind(data=pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]}))  # pd.DataFrame
     'matrix'

From 69cf33d2a07f123d1828d4dc384e9ff6e744e096 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 2 Oct 2024 21:35:59 +0800
Subject: [PATCH 3/6] Fix some docstrings

---
 pygmt/tests/test_grdtrack.py    | 4 ++--
 pygmt/tests/test_x2sys_cross.py | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/pygmt/tests/test_grdtrack.py b/pygmt/tests/test_grdtrack.py
index 4088da01ac8..a828db12ede 100644
--- a/pygmt/tests/test_grdtrack.py
+++ b/pygmt/tests/test_grdtrack.py
@@ -126,7 +126,7 @@ def test_grdtrack_profile(dataarray):
 
 def test_grdtrack_wrong_kind_of_points_input(dataarray, dataframe):
     """
-    Run grdtrack using points input that is not a pandas.DataFrame (matrix) or file.
+    Run grdtrack using points input that is not a pandas.DataFrame or file.
     """
     invalid_points = dataframe.longitude.to_xarray()
     with pytest.raises(GMTInvalidInput):
@@ -135,7 +135,7 @@ def test_grdtrack_wrong_kind_of_points_input(dataarray, dataframe):
 
 def test_grdtrack_wrong_kind_of_grid_input(dataarray, dataframe):
     """
-    Run grdtrack using grid input that is not as xarray.DataArray (grid) or file.
+    Run grdtrack using grid input that is not as xarray.DataArray or file.
     """
     invalid_grid = dataarray.to_dataset()
     with pytest.raises(GMTInvalidInput):
diff --git a/pygmt/tests/test_x2sys_cross.py b/pygmt/tests/test_x2sys_cross.py
index 00be06173a6..c72cca04420 100644
--- a/pygmt/tests/test_x2sys_cross.py
+++ b/pygmt/tests/test_x2sys_cross.py
@@ -236,8 +236,8 @@ def test_x2sys_cross_input_two_filenames():
 
 def test_x2sys_cross_invalid_tracks_input_type(tracks):
     """
-    Run x2sys_cross using tracks input that is not a pandas.DataFrame (matrix) or str
-    (file) type, which would raise a GMTInvalidInput error.
+    Run x2sys_cross using tracks input that is not a pandas.DataFrame or str type,
+    which would raise a GMTInvalidInput error.
     """
     invalid_tracks = tracks[0].to_xarray().z
     with pytest.raises(GMTInvalidInput):

From 13ec03faecae916be3ef3523c95efe95505716f8 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 2 Oct 2024 21:41:26 +0800
Subject: [PATCH 4/6] Improve docstrings

---
 pygmt/helpers/utils.py | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py
index 6140960ff38..4391998810e 100644
--- a/pygmt/helpers/utils.py
+++ b/pygmt/helpers/utils.py
@@ -207,13 +207,11 @@ def data_kind(
 
     Parameters
     ----------
-    data : str, pathlib.PurePath, None, bool, xarray.DataArray or {table-like}
-        Pass in either a file name or :class:`pathlib.Path` to an ASCII data
-        table, an :class:`xarray.DataArray`, a 1-D/2-D
-        {table-classes} or an option argument.
+    data
+        The data to be passed to a GMT module.
     required
-        Set to True when 'data' is required, or False when dealing with
-        optional virtual files. [Default is True].
+        Whether 'data' is required. Set to ``False`` when dealing with optional virtual
+        files.
 
     Returns
     -------

From 6d1e93f57a6f04a71c050bb50fdc30409d9d7d78 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 2 Oct 2024 21:51:34 +0800
Subject: [PATCH 5/6] Fix a typo

---
 pygmt/helpers/utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py
index 4391998810e..24a938df518 100644
--- a/pygmt/helpers/utils.py
+++ b/pygmt/helpers/utils.py
@@ -239,7 +239,7 @@ def data_kind(
     ['file', 'file']
     >>> data_kind(data=Path("file.txt"))
     'file'
-    >>> data_kind(data=(Path("file1.txt", "file2.txt")))
+    >>> data_kind(data=(Path("file1.txt"), Path("file2.txt")))
     'file'
 
     The "grid" kind:

From e80215a896478b55b0b8c44e283b4a40648696a9 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 3 Oct 2024 12:38:31 +0800
Subject: [PATCH 6/6] Fix a typo [skip ci]

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>
---
 pygmt/tests/test_grdtrack.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pygmt/tests/test_grdtrack.py b/pygmt/tests/test_grdtrack.py
index a828db12ede..8bfb6cf98fb 100644
--- a/pygmt/tests/test_grdtrack.py
+++ b/pygmt/tests/test_grdtrack.py
@@ -135,7 +135,7 @@ def test_grdtrack_wrong_kind_of_points_input(dataarray, dataframe):
 
 def test_grdtrack_wrong_kind_of_grid_input(dataarray, dataframe):
     """
-    Run grdtrack using grid input that is not as xarray.DataArray or file.
+    Run grdtrack using grid input that is not an xarray.DataArray or file.
     """
     invalid_grid = dataarray.to_dataset()
     with pytest.raises(GMTInvalidInput):