Deprecate pygmt.io.load_dataarray, use xarray.load_dataarray instead (#3922)

Deprecate usage of `pygmt.io.load_dataarray` for loading NetCDF
and other grids, use `xr.load_dataarray(..., engine="gmt")` instead.

* Switch from pygmt.io.load_dataarray to xr.load_dataarray

Specifically with arguments (..., engine="gmt", decode_kind="grid").

* Suggest passing raster_kind="grid" or "image" in FutureWarning message
* Move test_io_load_dataarray benchmark test to test_xarray_backend
* Replace pygmt.io.load_dataarray with xr.load_dataarray in tests
* Replace xr.open_dataarray with xr.load_dataarray in tests

Author: weiji14

pygmt/datasets/samples.py

@@ -8,7 +8,6 @@
 import pandas as pd
 import xarray as xr
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.io import load_dataarray
 from pygmt.src import which
 
 
@@ -204,7 +203,7 @@ def _load_earth_relief_holes() -> xr.DataArray:
         is in meters.
     """
     fname = which("@earth_relief_20m_holes.grd", download="c")
-    return load_dataarray(fname, engine="netcdf4")
+    return xr.load_dataarray(fname, engine="gmt", raster_kind="grid")
 
 
 class GMTSampleData(NamedTuple):

pygmt/helpers/testing.py

@@ -7,8 +7,8 @@
 import string
 from pathlib import Path
 
+import xarray as xr
 from pygmt.exceptions import GMTImageComparisonFailure
-from pygmt.io import load_dataarray
 from pygmt.src import which
 
 
@@ -154,7 +154,7 @@ def load_static_earth_relief():
         A grid of Earth relief for internal tests.
     """
     fname = which("@static_earth_relief.nc", download="c")
-    return load_dataarray(fname)
+    return xr.load_dataarray(fname, engine="gmt", raster_kind="grid")
 
 
 def skip_if_no(package):

pygmt/io.py

@@ -2,9 +2,12 @@
 PyGMT input/output (I/O) utilities.
 """
 
+import warnings
+
 import xarray as xr
 
 
+# TODO(PyGMT>=0.20.0): Remove pygmt.io.load_dataarray
 def load_dataarray(filename_or_obj, **kwargs):
     """
     Open, load into memory, and close a DataArray from a file or file-like object
@@ -19,6 +22,12 @@ def load_dataarray(filename_or_obj, **kwargs):
     to :py:func:`xarray.open_dataarray`. See that documentation for further
     details.
 
+    .. deprecated:: v0.16.0
+       The 'pygmt.io.load_dataarray' function will be removed in v0.20.0. Please use
+       `xarray.load_dataarray(..., engine='gmt', raster_kind='grid')` instead if you
+       were reading grids using the engine='netcdf'; otherwise use `raster_kind='image'`
+       if you were reading multi-band images using engine='rasterio'.
+
     Parameters
     ----------
     filename_or_obj : str or pathlib.Path or file-like or DataStore
@@ -37,6 +46,15 @@ def load_dataarray(filename_or_obj, **kwargs):
     --------
     xarray.open_dataarray
     """
+    msg = (
+        "The 'pygmt.io.load_dataarray' function will be removed in v0.20.0. Please use "
+        "`xarray.load_dataarray(..., engine='gmt', raster_kind='grid')` instead if you "
+        "were reading grids using the engine='netcdf'; otherwise use "
+        "`raster_kind='image'` if you were reading multi-band images using "
+        "engine='rasterio'."
+    )
+    warnings.warn(message=msg, category=FutureWarning, stacklevel=1)
+
     if "cache" in kwargs:
         msg = "'cache' has no effect in this context."
         raise TypeError(msg)

pygmt/tests/test_clib_put_matrix.py

@@ -111,12 +111,14 @@ def test_put_matrix_grid(dtypes):
                     tmp_grid.name,
                     grid,
                 )
-                with xr.open_dataarray(tmp_grid.name) as dataarray:
-                    assert dataarray.shape == shape
-                    npt.assert_allclose(dataarray.data, np.flipud(data))
-                    npt.assert_allclose(
-                        dataarray.coords["x"].actual_range, np.array(wesn[0:2])
-                    )
-                    npt.assert_allclose(
-                        dataarray.coords["y"].actual_range, np.array(wesn[2:4])
-                    )
+                dataarray = xr.load_dataarray(
+                    tmp_grid.name, engine="gmt", raster_kind="grid"
+                )
+                assert dataarray.shape == shape
+                npt.assert_allclose(dataarray.data, np.flipud(data))
+                npt.assert_allclose(
+                    dataarray.coords["x"].actual_range, np.array(wesn[0:2])
+                )
+                npt.assert_allclose(
+                    dataarray.coords["y"].actual_range, np.array(wesn[2:4])
+                )

pygmt/tests/test_clib_read_data.py

@@ -11,7 +11,6 @@
 from pygmt.clib import Session
 from pygmt.exceptions import GMTCLibError
 from pygmt.helpers import GMTTempFile
-from pygmt.io import load_dataarray
 from pygmt.src import which
 
 try:
@@ -27,7 +26,9 @@ def fixture_expected_xrgrid():
     """
     The expected xr.DataArray object for the static_earth_relief.nc file.
     """
-    return load_dataarray(which("@static_earth_relief.nc"))
+    return xr.load_dataarray(
+        "@static_earth_relief.nc", engine="gmt", raster_kind="grid"
+    )
 
 
 @pytest.fixture(scope="module", name="expected_xrimage")

pygmt/tests/test_dimfilter.py

@@ -6,7 +6,7 @@
 
 import pytest
 import xarray as xr
-from pygmt import dimfilter, load_dataarray
+from pygmt import dimfilter
 from pygmt.enums import GridRegistration, GridType
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import GMTTempFile
@@ -57,7 +57,7 @@ def test_dimfilter_outgrid(grid, expected_grid):
         )
         assert result is None  # return value is None
         assert Path(tmpfile.name).stat().st_size > 0  # check that outgrid exists
-        temp_grid = load_dataarray(tmpfile.name)
+        temp_grid = xr.load_dataarray(tmpfile.name, engine="gmt", raster_kind="grid")
         xr.testing.assert_allclose(a=temp_grid, b=expected_grid)
 
 

pygmt/tests/test_grdclip.py

@@ -8,7 +8,7 @@
 import numpy.testing as npt
 import pytest
 import xarray as xr
-from pygmt import grdclip, load_dataarray
+from pygmt import grdclip
 from pygmt.datasets import load_earth_mask
 from pygmt.enums import GridRegistration, GridType
 from pygmt.exceptions import GMTInvalidInput
@@ -54,7 +54,7 @@ def test_grdclip_outgrid(grid, expected_grid):
         )
         assert result is None  # return value is None
         assert Path(tmpfile.name).stat().st_size > 0  # check that outgrid exists
-        temp_grid = load_dataarray(tmpfile.name)
+        temp_grid = xr.load_dataarray(tmpfile.name, engine="gmt", raster_kind="grid")
         assert temp_grid.dims == ("lat", "lon")
         assert temp_grid.gmt.gtype == GridType.GEOGRAPHIC
         assert temp_grid.gmt.registration == GridRegistration.PIXEL

pygmt/tests/test_grdcut.py

@@ -5,7 +5,7 @@
 import numpy as np
 import pytest
 import xarray as xr
-from pygmt import grdcut, load_dataarray
+from pygmt import grdcut
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import GMTTempFile
 from pygmt.helpers.testing import load_static_earth_relief
@@ -50,7 +50,7 @@ def test_grdcut_dataarray_in_file_out(grid, expected_grid, region):
     with GMTTempFile(suffix=".nc") as tmpfile:
         result = grdcut(grid, outgrid=tmpfile.name, region=region)
         assert result is None  # grdcut returns None if output to a file
-        temp_grid = load_dataarray(tmpfile.name)
+        temp_grid = xr.load_dataarray(tmpfile.name, engine="gmt", raster_kind="grid")
         xr.testing.assert_allclose(a=temp_grid, b=expected_grid)
 
 

pygmt/tests/test_grdfill.py

@@ -8,7 +8,7 @@
 import numpy.testing as npt
 import pytest
 import xarray as xr
-from pygmt import grdfill, load_dataarray
+from pygmt import grdfill
 from pygmt.enums import GridRegistration, GridType
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import GMTTempFile
@@ -96,7 +96,7 @@ def test_grdfill_file_out(grid, expected_grid):
         result = grdfill(grid=grid, constantfill=20, outgrid=tmpfile.name)
         assert result is None  # return value is None
         assert Path(tmpfile.name).stat().st_size > 0  # check that outfile exists
-        temp_grid = load_dataarray(tmpfile.name)
+        temp_grid = xr.load_dataarray(tmpfile.name, engine="gmt", raster_kind="grid")
         xr.testing.assert_allclose(a=temp_grid, b=expected_grid)
 
 

pygmt/tests/test_grdfilter.py

@@ -7,7 +7,7 @@
 import numpy as np
 import pytest
 import xarray as xr
-from pygmt import grdfilter, load_dataarray
+from pygmt import grdfilter
 from pygmt.enums import GridRegistration, GridType
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import GMTTempFile
@@ -71,7 +71,7 @@ def test_grdfilter_dataarray_in_file_out(grid, expected_grid):
         )
         assert result is None  # return value is None
         assert Path(tmpfile.name).stat().st_size > 0  # check that outgrid exists
-        temp_grid = load_dataarray(tmpfile.name)
+        temp_grid = xr.load_dataarray(tmpfile.name, engine="gmt", raster_kind="grid")
         xr.testing.assert_allclose(a=temp_grid, b=expected_grid)