Wrap nearneighbor

[JamieJQuinn]

Description of proposed changes

This PR adds an implementation of nearneighbor, mirroring that of the already implemented surface.

The documentation has been cobbled together from similar portions in
surface and from the official GMT documentation on
nearneighbor.
Additional long-form flags have been added, reflecting the flags
particularly useful for nearneighbor, mainly -Ssearch_radius,
-Eempty and -Nsectors.

Tests have been blatantly copied from those testing surface, since the
two functions should operate broadly similarly.

The nearneighbor command is particularly important for remove-restore, an algorithm used to combine different datasets into one grid. In my case, this is implemented in a package I manage, pyCascadia, which is using pyGMT to implement remove-restore for the purposes of combining bathymetry datasets. It would be useful to pyCascadia to have nearneighbor implemented to the same degree as e.g. surface.

Preview docs at https://pygmt-git-fork-jamiejquinn-feature-implement-nearneighbour-gmt.vercel.app/api/generated/pygmt.nearneighbor.html

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.

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

[welcome]

💖 Thanks for opening this pull request! 💖

Please make sure you read our contributing guidelines and abide by our code of conduct.

A few things to keep in mind:

• If you need help writing tests, take a look at the existing ones for inspiration. If you don't know where to start, let us know and we'll walk you through it.
• All new features should be documented. It helps to write the docstrings for your functions/classes before writing the code. This will help you think about your code design and results in better code.
• No matter what, we are really grateful that you put in the effort to do this! 🎉

[weiji14]

Hi @JamieJQuinn, thank you for opening up this PR! I see that you have a parallel implementation over at UCL/pyCascadia#65, so good on you for bringing this into PyGMT. Overall, your implementation is actually solid and works properly. I have listed a few suggested changes below, mostly related to modernization of the code style (the surface module you based your code on hasn't really been updated since 2019).

If you agree to the changes, feel free to do a "Commit suggestion" directly, or pool several together using "Add suggestion to batch" before committing. See also https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request#applying-a-suggested-change.

[JamieJQuinn]

@weiji14 cheers for the suggestions!

[weiji14]

I'm more or less happy with the implementation here, aside from a couple of tiny things. Would appreciate it if someone from @GenericMappingTools/pygmt-maintainers takes a look too.

[willschlitzer]

Looks good to me (but agree with @weiji14's two suggestions)!

[weiji14]

Maintainers, please give this a final review (docs preview at https://pygmt-git-fork-jamiejquinn-feature-implement-nearneighbour-gmt.vercel.app/api/generated/pygmt.nearneighbor.html), and if there are no major objections, will merge in ~24 hours 🚀

[seisman]

Looks good to me except for two suggestions on docstrings.

[welcome]

🎉🎉🎉 Congrats on merging your first pull request and welcome to the team! 🎉🎉🎉

Please open a new pull request to add yourself to the AUTHORS.md file. We hope that this was a good experience for you. Let us know if there is any way that the contributing process could be improved.

[weiji14]

Thanks again for your contribution @JamieJQuinn 😄 The nearneighbor function will be included in PyGMT v0.5.0, but if you can't wait for that, feel free to install the development version following https://www.pygmt.org/dev/install.html#using-pip:

pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt

This will install the version of PyGMT from TestPyPI at https://test.pypi.org/project/pygmt/0.4.2.dev64. Oh, and you're welcome to send in new feature requests or ideas to our issue tracker at https://github.com/GenericMappingTools/pygmt/issues. Looking forward to seeing you around more!

[willschlitzer]

@JamieJQuinn Feel free to open up a pull request to add yourself to AUTHORS.md if you would like! We have our v0.5.0 release scheduled for tomorrow that will include nearneighbor.