Remove the dependency of netCDF4

.github/workflows/benchmarks.yml

@@ -57,7 +57,6 @@ jobs:
             numpy
             pandas
             xarray
-            netCDF4
             packaging
             geopandas
             pyarrow-core

.github/workflows/cache_data.yaml

@@ -52,7 +52,6 @@ jobs:
             numpy
             pandas
             xarray
-            netCDF4
             packaging
             python-build
 

.github/workflows/ci_docs.yml

@@ -93,7 +93,6 @@ jobs:
             numpy
             pandas
             xarray
-            netCDF4
             packaging
             contextily
             geopandas

.github/workflows/ci_doctests.yaml

@@ -51,7 +51,6 @@ jobs:
             numpy
             pandas
             xarray
-            netCDF4
             packaging
             contextily
             geopandas

.github/workflows/ci_tests.yaml

@@ -128,7 +128,6 @@ jobs:
             numpy=${{ matrix.numpy-version }}
             pandas${{ matrix.pandas-version }}
             xarray${{ matrix.xarray-version }}
-            netCDF4
             packaging
             make
             pip

.github/workflows/ci_tests_dev.yaml

@@ -146,8 +146,8 @@ jobs:
         run: |
           python -m pip install --pre --prefer-binary \
                         --extra-index https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \
-                        numpy pandas xarray netCDF4 packaging \
-                        build contextily dvc geopandas ipython pyarrow rioxarray \
+                        numpy pandas xarray packaging \
+                        build contextily dvc geopandas ipython pyarrow rioxarray netCDF4 \
                         pytest pytest-cov pytest-doctestplus pytest-mpl pytest-rerunfailures \
                         sphinx-gallery
 

.github/workflows/ci_tests_legacy.yaml

@@ -61,13 +61,13 @@ jobs:
             numpy<2
             pandas
             xarray
-            netCDF4
             packaging
             contextily
             geopandas
             ipython
             pyarrow-core
             rioxarray
+            netCDF4
             sphinx-gallery
             make
             pip

.github/workflows/type_checks.yml

@@ -49,7 +49,7 @@ jobs:
           # 3. type checker and stub packages
           # 4. other packages that are used somewhere in PyGMT
           python -m pip install \
-            numpy pandas xarray netcdf4 packaging \
+            numpy pandas xarray packaging \
             contextily geopandas ipython pyarrow rioxarray \
             mypy pandas-stubs pyarrow-stubs \
             matplotlib pytest

ci/requirements/docs.yml

@@ -10,7 +10,6 @@ dependencies:
     - numpy
     - pandas
     - xarray
-    - netCDF4
     - packaging
     # Optional dependencies
     - contextily

doc/api/index.rst

@@ -174,6 +174,7 @@ Input/output
     :toctree: generated
 
     load_dataarray
+    read
 
 GMT Defaults
 ------------

doc/install.md

@@ -95,7 +95,6 @@ PyGMT requires the following packages to be installed:
 - [NumPy](https://numpy.org)
 - [pandas](https://pandas.pydata.org)
 - [Xarray](https://xarray.dev/)
-- [netCDF4](https://unidata.github.io/netcdf4-python)
 - [packaging](https://packaging.pypa.io)
 
 :::{note}
@@ -128,14 +127,14 @@ installed (we'll call it `pygmt` but feel free to change it to whatever you want
 ::: {tab-item} mamba
 :sync: mamba
 ```
-mamba create --name pygmt python=3.13 numpy pandas xarray netcdf4 packaging gmt
+mamba create --name pygmt python=3.13 numpy pandas xarray packaging gmt
 ```
 :::
 
 ::: {tab-item} conda
 :sync: conda
 ```
-conda create --name pygmt python=3.13 numpy pandas xarray netcdf4 packaging gmt
+conda create --name pygmt python=3.13 numpy pandas xarray packaging gmt
 ```
 :::
 ::::

environment.yml

@@ -10,7 +10,6 @@ dependencies:
     - numpy>=1.25
     - pandas>=2.0
     - xarray>=2023.04
-    - netCDF4
     - packaging
     # Optional dependencies
     - contextily
@@ -34,6 +33,8 @@ dependencies:
     - pytest-cov
     - pytest-doctestplus
     - pytest-mpl
+    # Dev dependencies (testing)
+    - netCDF4
     # Dev dependencies (building documentation)
     - geodatasets
     - myst-nb

pygmt/__init__.py

@@ -54,6 +54,7 @@
     makecpt,
     nearneighbor,
     project,
+    read,
     select,
     sph2grd,
     sphdistance,

pygmt/datasets/samples.py

@@ -8,8 +8,7 @@
 import pandas as pd
 import xarray as xr
 from pygmt.exceptions import GMTInvalidInput
-from pygmt.io import load_dataarray
-from pygmt.src import which
+from pygmt.src import read, which
 
 
 def _load_japan_quakes() -> pd.DataFrame:
@@ -203,8 +202,7 @@ def _load_earth_relief_holes() -> xr.DataArray:
         The Earth relief grid. Coordinates are latitude and longitude in degrees. Relief
         is in meters.
     """
-    fname = which("@earth_relief_20m_holes.grd", download="c")
-    return load_dataarray(fname, engine="netcdf4")
+    return read("@earth_relief_20m_holes.grd", kind="grid")  # type: ignore[return-value]
 
 
 class GMTSampleData(NamedTuple):

pygmt/helpers/testing.py

@@ -7,9 +7,9 @@
 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
+from pygmt.src import read
 
 
 def check_figures_equal(*, extensions=("png",), tol=0.0, result_dir="result_images"):
@@ -144,17 +144,16 @@ def wrapper(*args, ext="png", request=None, **kwargs):
     return decorator
 
 
-def load_static_earth_relief():
+def load_static_earth_relief() -> xr.DataArray:
     """
-    Load the static_earth_relief file for internal testing.
+    Load the static_earth_relief.nc file for internal testing.
 
     Returns
     -------
-    data : xarray.DataArray
+    data
         A grid of Earth relief for internal tests.
     """
-    fname = which("@static_earth_relief.nc", download="c")
-    return load_dataarray(fname)
+    return read("@static_earth_relief.nc", kind="grid")  # type: ignore[return-value]
 
 
 def skip_if_no(package):

pygmt/src/__init__.py

@@ -42,6 +42,7 @@
 from pygmt.src.plot3d import plot3d
 from pygmt.src.project import project
 from pygmt.src.psconvert import psconvert
+from pygmt.src.read import read
 from pygmt.src.rose import rose
 from pygmt.src.select import select
 from pygmt.src.shift_origin import shift_origin

pygmt/src/grdcut.py

@@ -2,23 +2,24 @@
 grdcut - Extract subregion from a grid.
 """
 
+from typing import Literal
+
 import xarray as xr
 from pygmt.clib import Session
+from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
-    GMTTempFile,
     build_arg_list,
+    data_kind,
     fmt_docstring,
     kwargs_to_strings,
     use_alias,
 )
-from pygmt.io import load_dataarray
 
 __doctest_skip__ = ["grdcut"]
 
 
 @fmt_docstring
 @use_alias(
-    G="outgrid",
     R="region",
     J="projection",
     N="extend",
@@ -28,9 +29,11 @@
     f="coltypes",
 )
 @kwargs_to_strings(R="sequence")
-def grdcut(grid, **kwargs) -> xr.DataArray | None:
+def grdcut(
+    grid, kind: Literal["grid", "image"] = "grid", outgrid: str | None = None, **kwargs
+) -> xr.DataArray | None:
     r"""
-    Extract subregion from a grid.
+    Extract subregion from a grid or image.
 
     Produce a new ``outgrid`` file which is a subregion of ``grid``. The
     subregion is specified with ``region``; the specified range must not exceed
@@ -48,6 +51,10 @@
     Parameters
     ----------
     {grid}
+    kind
+        The raster data kind. Valid values are ``grid`` and ``image``. When the input
+        ``grid`` is a file name, it's hard to determine if the file is a grid or an
+        image, so we need to specify the kind explicitly. The default is ``grid``.
     {outgrid}
     {projection}
     {region}
@@ -100,13 +107,23 @@
     >>> # 12° E to 15° E and a latitude range of 21° N to 24° N
     >>> new_grid = pygmt.grdcut(grid=grid, region=[12, 15, 21, 24])
     """
-    with GMTTempFile(suffix=".nc") as tmpfile:
-        with Session() as lib:
-            with lib.virtualfile_in(check_kind="raster", data=grid) as vingrd:
-                if (outgrid := kwargs.get("G")) is None:
-                    kwargs["G"] = outgrid = tmpfile.name  # output to tmpfile
-                lib.call_module(
-                    module="grdcut", args=build_arg_list(kwargs, infile=vingrd)
-                )
+    # Determine the output data kind based on the input data kind.
+    match inkind := data_kind(grid):
+        case "image" | "grid":
+            outkind = inkind
+        case "file":
+            outkind = kind
+        case "_":
+            msg = f"Unsupported data type {type(grid)}."
+            raise GMTInvalidInput(msg)
 
-        return load_dataarray(outgrid) if outgrid == tmpfile.name else None
+    with Session() as lib:
+        with (
+            lib.virtualfile_in(check_kind="raster", data=grid) as vingrd,
+            lib.virtualfile_out(kind=outkind, fname=outgrid) as voutgrd,
+        ):
+            kwargs["G"] = voutgrd
+            lib.call_module(module="grdcut", args=build_arg_list(kwargs, infile=vingrd))
+            return lib.virtualfile_to_raster(
+                vfname=voutgrd, kind=outkind, outgrid=outgrid
+            )