Merge branch 'data_kind/doctest' into refactor/data_kind

Author: seisman

pygmt/helpers/utils.py

@@ -229,6 +229,7 @@ def data_kind(  # noqa: PLR0911
 
     Examples
     --------
+    <<<<<<< HEAD
     >>> import numpy as np
     >>> import xarray as xr
     >>> import pandas as pd
@@ -247,20 +248,72 @@ def data_kind(  # noqa: PLR0911
     >>> data_kind(data=["data1.txt", "data2.txt"])
     'file'
     >>> data_kind(data=xr.DataArray(np.random.rand(4, 3)))
+    =======
+    >>> import io
+    >>> from pathlib import Path
+    >>> import numpy as np
+    >>> import pandas as pd
+    >>> import xarray as xr
+
+    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'
+
+    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.random.rand(3, 4, 5)))
+    >>> 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'
+
+    The "image" kind:
+
+    >>> data_kind(data=xr.DataArray(np.random.rand(3, 4, 5)))  # 3-D xarray.DataArray
     'image'
-    >>> data_kind(data=np.arange(10).reshape((5, 2)))
-    'matrix'
+
+    The "stringio"`` kind:
+
     >>> data_kind(data=io.StringIO("TEXT1\nTEXT23\n"))
     'stringio'
-    >>> data_kind(data=pd.DataFrame(data={"col1": [1, 2], "col2": [3, 4]}))
-    'vectors'
-    >>> data_kind(data={"x": [1, 2], "y": [3, 4]})
-    'vectors'
-    >>> data_kind(data=[[1, 2], [3, 4]])
-    'vectors'
-    >>> data_kind(data=[1, 2, 3])
+
+    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]})  # dictionary
+    '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'
     """
     # data is None and is required.

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])
 

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])
 

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"

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 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) == "vectors"
     with pytest.raises(GMTInvalidInput):
         grdtrack(points=dataframe, grid=invalid_grid, newcolname="bathymetry")
 

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) == "vectors"
-
     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) == "vectors"
-
     fig = Figure()
     with pytest.raises(GMTInvalidInput):
         fig.grdview(grid=xrgrid, drapegrid=dataset)

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"

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)
 

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)
 

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])