Add inline example for xyz2grd

[willschlitzer]

This PR adds an inline code example to the docstring for xyz2grd.

Addresses #1686

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[seisman]

As I understand it, xyz2grd doesn't do interpolations, so for densely sampled data like the bathymetry data, calling xyz2grd with a coarse spacing (spacing=5) produces a grid that cannot reflect the original data. Thus, I think this is not a good example for xyz2grd which may mislead users.

[willschlitzer]

What would you recommend instead?

[seisman]

Perhaps passing a 2D numpy array is a more useful example, for example:

importnumpyasnpimportpygmt# prepare input arraysx, y=np.meshgrid([0, 1, 2, 3], [10.5, 11.0, 11.5, 12.0, 12.5])
z=x**2+y**2xx, yy, zz=x.flatten(), y.flatten(), z.flatten()
grid=pygmt.xyz2grd(x=xx, y=yy, z=zz, spacing=(1.0, 0.5))

[willschlitzer]

I'm not a geoscientist, so I'm not sure how realistic this example is. But this seems confusing, because it uses numpy functions outside of simple math operations. Would be be easier to just pass a numpy array of data?

[seisman]

The equivalent 2d numpy array would be like this:

array([[ 0. , 10.5 , 110.25],
[ 1. , 10.5 , 111.25],
[ 2. , 10.5 , 114.25],
[ 3. , 10.5 , 119.25],
[ 0. , 11. , 121. ],
[ 1. , 11. , 122. ],
[ 2. , 11. , 125. ],
[ 3. , 11. , 130. ],
[ 0. , 11.5 , 132.25],
[ 1. , 11.5 , 133.25],
[ 2. , 11.5 , 136.25],
[ 3. , 11.5 , 141.25],
[ 0. , 12. , 144. ],
[ 1. , 12. , 145. ],
[ 2. , 12. , 148. ],
[ 3. , 12. , 153. ],
[ 0. , 12.5 , 156.25],
[ 1. , 12.5 , 157.25],
[ 2. , 12.5 , 160.25],
[ 3. , 12.5 , 165.25]])

People usually know the X range and Y range of the grid, but may don't know how to prepare a 2D numpy array for PyGMT.

Here is a similar example in matplotlib: https://matplotlib.org/stable/plot_types/arrays/pcolormesh.html.

The main difference is that, we have to call the array.flatten() method before passing to xyz2grd.

[seisman]

/format

[seisman]

The doctest example fails with the following error message:

??? >>> grid = pygmt.xyz2grd(x=xx, y=yy, z=zz, spacing=(1.0, 0.5))
UNEXPECTED EXCEPTION: GMTCLibError("Module 'xyz2grd' failed with status code 72:\nxyz2grd [ERROR]: Option -I: Given more than once (offending option is -I1.0)\nxyz2grd [ERROR]: Must specify -R option")
Traceback (most recent call last):
File "/Users/seisman/opt/miniconda/lib/python3.9/doctest.py", line 1336, in __run
exec(compile(example.source, filename, "single",
File "<doctest pygmt.src.xyz2grd.xyz2grd[5]>", line 1, in <module>
File "/Users/seisman/OSS/gmt/pygmt/pygmt/helpers/decorators.py", line 585, in new_module
return module_func(*args, **kwargs)
File "/Users/seisman/OSS/gmt/pygmt/pygmt/helpers/decorators.py", line 725, in new_module
return module_func(*args, **kwargs)
File "/Users/seisman/OSS/gmt/pygmt/pygmt/src/xyz2grd.py", line 158, in xyz2grd
lib.call_module("xyz2grd", arg_str)
File "/Users/seisman/OSS/gmt/pygmt/pygmt/clib/session.py", line 502, in call_module
raise GMTCLibError(
pygmt.exceptions.GMTCLibError: Module 'xyz2grd' failed with status code 72:
xyz2grd [ERROR]: Option -I: Given more than once (offending option is -I1.0)
xyz2grd [ERROR]: Must specify -R option

There are two problems here:

1. -R option is always required for xyz2grd
2. Need to add I="sequence" in @kwargs_to_strings to make spacing=(1.0, 0.5) work.

[seisman]

The doctest example fails with the following error message:

??? >>> grid = pygmt.xyz2grd(x=xx, y=yy, z=zz, spacing=(1.0, 0.5))
UNEXPECTED EXCEPTION: GMTCLibError("Module 'xyz2grd' failed with status code 72:\nxyz2grd [ERROR]: Option -I: Given more than once (offending option is -I1.0)\nxyz2grd [ERROR]: Must specify -R option")
Traceback (most recent call last):
File "/Users/seisman/opt/miniconda/lib/python3.9/doctest.py", line 1336, in __run
exec(compile(example.source, filename, "single",
File "<doctest pygmt.src.xyz2grd.xyz2grd[5]>", line 1, in <module>
File "/Users/seisman/OSS/gmt/pygmt/pygmt/helpers/decorators.py", line 585, in new_module
return module_func(*args, **kwargs)
File "/Users/seisman/OSS/gmt/pygmt/pygmt/helpers/decorators.py", line 725, in new_module
return module_func(*args, **kwargs)
File "/Users/seisman/OSS/gmt/pygmt/pygmt/src/xyz2grd.py", line 158, in xyz2grd
lib.call_module("xyz2grd", arg_str)
File "/Users/seisman/OSS/gmt/pygmt/pygmt/clib/session.py", line 502, in call_module
raise GMTCLibError(
pygmt.exceptions.GMTCLibError: Module 'xyz2grd' failed with status code 72:
xyz2grd [ERROR]: Option -I: Given more than once (offending option is -I1.0)
xyz2grd [ERROR]: Must specify -R option

There are two problems here:

1. -R option is always required for xyz2grd
2. Need to add I="sequence" in @kwargs_to_strings to make spacing=(1.0, 0.5) work.

Addressed in #1804.

[weiji14]

@willschlitzer, for the sake of Pi-Day, I can only approve either this xyz2grd PR or the grdvolume PR at #1299 for v0.6.0 (see #1808 (comment)). So which will it be?

[willschlitzer]

@willschlitzer, for the sake of Pi-Day, I can only approve either this xyz2grd PR or the grdvolume PR at #1299 for v0.6.0 (see #1808 (comment)). So which will it be?

Doesn't matter to me

[weiji14]

Let's do this one then