GenericMappingTools / GenericMappingTools/pygmt

pygmt.xyz2grd: Allow more flexible ways to pass x/y/z arrays

Open
#2,852 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
874
Forks
255
Avg merge
1d 21h
Merged PRs (30d)
40

Description

The [`pygmt.xyz2grd`](https://www.pygmt.org/dev/api/generated/pygmt.xyz2grd.html) function accepts 1-D x/y/z arrays as input and produces a grid. Here, x/y are the x- and y-coordinates of grid nodes and z is the data values on grid nodes. Thus, for a 3x4 grid, x/y/z arrays all have 12 values (assuming it's gridline-registrated).

The `pygmt.xyz2grd` API documentation provides a simple example showing how we should prepare the x/y/z arrays.
```python
import numpy as np
import pygmt

def func(x, y):
return x**2 + y**2

x, y = np.meshgrid([0, 1, 2, 3], [10.5, 11.0, 11.5, 12.0, 12.5])
z = func(x, y)
xx, yy, zz = x.flatten(), y.flatten(), z.flatten()
grid = pygmt.xyz2grd(x=xx, y=yy, z=zz, spacing=(1.0, 0.5), region=[0, 3, 10, 13])
```
As you can see, we have to use `np.meshgrid` to generate the 2-D x/y arrays, call a function (here `z=x**2+y**2`) to produce the 2-D z array, and use the `flatten()` method to convert the 2-D arrays into 1-D arrays. It's not straightforward and sometimes difficult to understand.

Here I propose to provide two more flexible ways to pass x/y/z arrays. The expected syntaxes are:
```python
x = [0, 1, 2, 3]
y = [10.5, 11.0, 11.5, 12.0, 12.5]
z = func(*np.meshgrid(x, y))

# Case 1: 2-D z array + 1-D x/y arrays
grid = pygmt.grid(x=x, y=y, z=z) # spacing and region are no longer needed

# Case 2: 2-D z array + region + spacing
grid = pygmt.grid(z=z, region=[0, 3, 10.5, 12.5], spacing=(1, 0.5))
```

Some notes:
1. Internally we should do something like before passing data to the `xyz2grd` module:
```
x = np.arange(region[0], region[1], spacing[0]) # required for case 2
y = np.arange(region[2], region[3], spacing[1]) # required for case 2
xx, yy = np.meshgrid(x, y)
xx, yy, zz = xx.flatten(), yy.flatten(), z.flatten()
# now pass xx/yy/zz to xyz2grd
```
2. The `-I` option (`spacing` parameter) is required for `xyz2grd`. The spacings can be obtained by `spacing = (x[1] - x[0], y[1] - y[0])` assuming that `x` and `y` are equal-spaced.
4. For case 2, a special case is, only the 2-D **z** array is given and `region`/`spacing` are not given, then `region` is default to [0, nx-1, 0, ny-1], and spacing is default to `[1, 1]`
5. In all cases, we need to be careful with the `registration` parameter.

Comments?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.