Wrap triangulate

[weiji14]

Description of proposed changes

Wrapping the triangulate function which does "Delaunay triangulation or Voronoi partitioning and gridding of Cartesian data", implemented under gridding.py. For a GMT example, see https://docs.generic-mapping-tools.org/6.3/gallery/ex16.html

Preview for this Pull Request is at https://pygmt-git-gridding-triangulate-gmt.vercel.app/api/generated/pygmt.triangulate.html

Note that this is a fairly minimal implementation of triangulate for now, and I don't expect to wrap and test all the aliases here as they are super complicated. Just that I've just been using triangulate secretly at https://github.com/weiji14/pyissm/blob/5c9e3be4c4983ccc79a67cc6471421922e8c3af7/plot_figures.py#L68-L83 and thought it should get into pygmt proper 😄

The complicated thing about triangulate is that it generates either text (table) or NetCDF (grid) outputs, and I've implemented it similar to grdhisteq at #1433 as so:

• triangulate.delaunay_triples:
  • When output_type="numpy", output table as numpy.ndarray
  • When output_type="pandas" (default for table), output table as pandas.DataFrame
  • When output_type="file" and outfile is not None, output table as textfile
• triangulate.regular_grid:
  • When outgrid=True (default for grid), output grid as 'xarray.DataArray`
  • When outgrid="test.nc", output grid to NetCDF file

Welcome to other suggestions on implementation details.

Fixes #

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 adding new functionality, add an example to docstrings or tutorials.

Notes

• You can write /format in the first line of a comment to lint the code automatically

[seisman]

When outgrid=None, output grid to NetCDF file

Typo?

When outgrid=None (default), output table as pandas.DataFrame
(Won't be implemented?), output table as textfile

I've never used this module, but how does GMT know the output type (a text file or a netcdf grid)?

[weiji14]

When outgrid=None, output grid to NetCDF file

Typo?

Good catch, should be when outgrid="test.nc" I've updated top post.

When outgrid=None (default), output table as pandas.DataFrame
(Won't be implemented?), output table as textfile

I've never used this module, but how does GMT know the output type (a text file or a netcdf grid)?

So in pure GMT, triangulate outputs to a table format (technically stdout) with rows and columns. But using -Gtest.nc would interpolate that table result into a square grid output.

[seisman]

So in pure GMT, triangulate outputs to a table format (technically stdout) with rows and columns. But using -Gtest.nc would interpolate that table result into a square grid output.

OK. Two solutions for me:

1. Don't implement the "output to text file" feature. It's easy to save the returned pandas.DataFrame to a text file.
2. Add a new parameter outfile. Save the output to outfile if it's not None.

[weiji14]

1. Don't implement the "output to text file" feature. It's easy to save the returned pandas.DataFrame to a text file.

Yep, Option 1 is the current state. Saving a pandas.DataFrame to an ASCII text file is definitely easier (compared to saving an xarray.DataArray to a NetCDF).

2. Add a new parameter outfile. Save the output to outfile if it's not None.

I thought about using outfile as well, and it's definitely implementable, though having 4 possible output types might confuse users. At some point though, this Option 2 might need to be done.

[seisman]

I think we can adopt option 1 now and add the outfile argument if requested.

[weiji14]

This is a bit of an old PR (~9 months), but a good one to put in for PyGMT v0.5.0 I think. Ping @GenericMappingTools/pygmt-maintainers for a review if free. The triangulate function as implemented takes an input table, and outputs either a table or grid.

[maxrjones]

Great work! These should be my last comments.

Should an exception be raised if output_type == "file" and outfile is None? For example:

pygmt.triangulate.delaunay_triples(
    data="@Table_5_11_mean.xyz",
    output_type="file"
)

The ongoing issues with uninformative error messages affect this PR, but that shouldn't hold back this feature.

[weiji14]

Should an exception be raised if output_type == "file" and outfile is None? For example:

pygmt.triangulate.delaunay_triples(
    data="@Table_5_11_mean.xyz",
    output_type="file"
)

Yes an exception should be raised, but this is not specific to triangulate. I think we'll need to handle this across the board in #1318.

[maxrjones]

Yes an exception should be raised, but this is not specific to triangulate. I think we'll need to handle this across the board in #1318.

Sounds good to deal with this separately (after v0.6.0). Of course I would have liked to fix that issue before this release, but this year has been going by too fast...

[maxrjones]

Looks good to me, thanks for all your work on this feature!

[seisman]

I've never used triangulate, so just two general comments.