Wrap grd2xyz

doc/api/index.rst

@@ -89,6 +89,7 @@ Operations on grids:
 .. autosummary::
  :toctree: generated
 
+ grd2xyz
  grdclip
  grdcut
  grdfill

pygmt/__init__.py

@@ -35,6 +35,7 @@
  blockmode,
  config,
  grd2cpt,
+ grd2xyz,
  grdclip,
  grdcut,
  grdfill,

pygmt/src/__init__.py

@@ -10,6 +10,7 @@
 from pygmt.src.config import config
 from pygmt.src.contour import contour
 from pygmt.src.grd2cpt import grd2cpt
+from pygmt.src.grd2xyz import grd2xyz
 from pygmt.src.grdclip import grdclip
 from pygmt.src.grdcontour import grdcontour
 from pygmt.src.grdcut import grdcut

pygmt/src/grd2xyz.py

@@ -0,0 +1,117 @@
+"""
+grd2xyz - Convert grid to data table
+"""
+import warnings
+
+import pandas as pd
+import xarray as xr
+from pygmt.clib import Session
+from pygmt.exceptions import GMTInvalidInput
+from pygmt.helpers import (
+ GMTTempFile,
+ build_arg_string,
+ fmt_docstring,
+ kwargs_to_strings,
+ use_alias,
+)
+
+
+@fmt_docstring
+@use_alias(
+ R="region",
+ V="verbose",
+ o="outcols",
+)
+@kwargs_to_strings(R="sequence", o="sequence_comma")
+def grd2xyz(grid, output_type="pandas", outfile=None, **kwargs):
+ r"""
+ Convert grid to data table.
+
+ Read a grid and output xyz-triplets as a :class:`numpy.ndarray`,
+ :class:`pandas.DataFrame`, or ASCII file.
+
+ Full option list at :gmt-docs:`grd2xyz.html`
+
+ {aliases}
+
+ Parameters
+ ----------
+ grid : str or xarray.DataArray
+ The file name of the input grid or the grid loaded as a
+ :class:`xarray.DataArray`. This is the only required parameter.
+ output_type : str
+ Determine the format the xyz data will be returned in [Default is
+ ``pandas``]:
+
+ - ``numpy`` - :class:`numpy.ndarray`
+ - ``pandas``- :class:`pandas.DataFrame`
+ - ``file`` - ASCII file (requires ``outfile``)
+ outfile : str
+ The file name for the output ASCII file.
+ {R}
+ Adding ``region`` will select a subsection of the grid. If this
+ subsection exceeds the boundaries of the grid, only the common region
+ will be output.
+ {V}
+ {o}
+
+ Returns
+ -------
+ ret : pandas.DataFrame or numpy.ndarray or None
+ Return type depends on ``outfile`` and ``output_type``:
+
+ - None if ``outfile`` is set (output will be stored in file set by
+ ``outfile``)
+ - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is
+ not set (depends on ``output_type``)
+
+ """
+ if output_type not in ["numpy", "pandas", "file"]:
+ raise GMTInvalidInput(
+ "Must specify 'output_type' either as 'numpy', 'pandas' or 'file'."
+ )
+
+ if outfile is not None and output_type != "file":
+ msg = (
+ f"Changing 'output_type' of grd2xyz from '{output_type}' to 'file' "
+ "since 'outfile' parameter is set. Please use output_type='file' "
+ "to silence this warning."
+ )
+ warnings.warn(message=msg, category=RuntimeWarning, stacklevel=2)
+ output_type = "file"
+ elif outfile is None and output_type == "file":
+ raise GMTInvalidInput("Must specify 'outfile' for ASCII output.")
+
+ if "o" in kwargs and output_type == "pandas":
+ raise GMTInvalidInput(
+ "If 'outcols' is specified, 'output_type' must be either 'numpy'"
+ "or 'file'."
+ )
+
+ # Set the default column names for the pandas dataframe header
+ dataframe_header = ["x", "y", "z"]
+ # Let output pandas column names match input DataArray dimension names
+ if isinstance(grid, xr.DataArray) and output_type == "pandas":
+ # Reverse the dims because it is rows, columns ordered.
+ dataframe_header = [grid.dims[1], grid.dims[0], grid.name]
+
+ with GMTTempFile() as tmpfile:
+ with Session() as lib:
+ file_context = lib.virtualfile_from_data(check_kind="raster", data=grid)
+ with file_context as infile:
+ if outfile is None:
+ outfile = tmpfile.name
+ arg_str = " ".join([infile, build_arg_string(kwargs), "->" + outfile])
+ lib.call_module("grd2xyz", arg_str)
+
+ # Read temporary csv output to a pandas table
+ if outfile == tmpfile.name: # if user did not set outfile, return pd.DataFrame
+ result = pd.read_csv(
+ tmpfile.name, sep="\t", names=dataframe_header, comment=">"
+ )
+ elif outfile != tmpfile.name: # return None if outfile set, output in outfile
+ result = None
+
+ if output_type == "numpy":
+ result = result.to_numpy()
+ return result

pygmt/tests/test_grd2xyz.py

@@ -0,0 +1,97 @@
+"""
+Tests for grd2xyz.
+"""
+import os
+
+import numpy as np
+import pandas as pd
+import pytest
+from pygmt import grd2xyz
+from pygmt.datasets import load_earth_relief
+from pygmt.exceptions import GMTInvalidInput
+from pygmt.helpers import GMTTempFile
+
+
+@pytest.fixture(scope="module", name="grid")
+def fixture_grid():
+ """
+ Load the grid data from the sample earth_relief file.
+ """
+ return load_earth_relief(resolution="01d", region=[-1, 1, 3, 5])
+
+
+def test_grd2xyz(grid):
+ """
+ Make sure grd2xyz works as expected.
+ """
+ xyz_data = grd2xyz(grid=grid, output_type="numpy")
+ assert xyz_data.shape == (4, 3)
+
+
+def test_grd2xyz_format(grid):
+ """
+ Test that correct formats are returned.
+ """
+ lon = -0.5
+ lat = 3.5
+ orig_val = grid.sel(lon=lon, lat=lat).to_numpy()
+ xyz_default = grd2xyz(grid=grid)
+ xyz_val = xyz_default[(xyz_default["lon"] == lon) & (xyz_default["lat"] == lat)][
+ "elevation"
+ ].to_numpy()
+ assert isinstance(xyz_default, pd.DataFrame)
+ assert orig_val.size == 1
+ assert xyz_val.size == 1
+ np.testing.assert_allclose(orig_val, xyz_val)
+ xyz_array = grd2xyz(grid=grid, output_type="numpy")
+ assert isinstance(xyz_array, np.ndarray)
+ xyz_df = grd2xyz(grid=grid, output_type="pandas")
+ assert isinstance(xyz_df, pd.DataFrame)
+ assert list(xyz_df.columns) == ["lon", "lat", "elevation"]
+
+
+def test_grd2xyz_file_output(grid):
+ """
+ Test that grd2xyz returns a file output when it is specified.
+ """
+ with GMTTempFile(suffix=".xyz") as tmpfile:
+ result = grd2xyz(grid=grid, outfile=tmpfile.name, output_type="file")
+ assert result is None # return value is None
+ assert os.path.exists(path=tmpfile.name) # check that outfile exists
+
+
+def test_grd2xyz_invalid_format(grid):
+ """
+ Test that grd2xyz fails with incorrect format.
+ """
+ with pytest.raises(GMTInvalidInput):
+ grd2xyz(grid=grid, output_type=1)
+
+
+def test_grd2xyz_no_outfile(grid):
+ """
+ Test that grd2xyz fails when a string output is set with no outfile.
+ """
+ with pytest.raises(GMTInvalidInput):
+ grd2xyz(grid=grid, output_type="file")
+
+
+def test_grd2xyz_outfile_incorrect_output_type(grid):
+ """
+ Test that grd2xyz raises a warning when an outfile filename is set but the
+ output_type is not set to 'file'.
+ """
+ with pytest.warns(RuntimeWarning):
+ with GMTTempFile(suffix=".xyz") as tmpfile:
+ result = grd2xyz(grid=grid, outfile=tmpfile.name, output_type="numpy")
+ assert result is None # return value is None
+ assert os.path.exists(path=tmpfile.name) # check that outfile exists
+
+
+def test_grd2xyz_pandas_output_with_o(grid):
+ """
+ Test that grd2xyz fails when outcols is set and output_type is set to
+ 'pandas'.
+ """
+ with pytest.raises(GMTInvalidInput):
+ grd2xyz(grid=grid, output_type="pandas", outcols="2")