Correct and consistent usage of 'function, 'method', and 'class'

[yvonnefroehlich]

Description of proposed changes

Fixes #2029

---

Overview of affected files

• Cross-check in the end regarding completeness

Examples which use 'function' for the methods of the pygmt.Figure class

• Making subplots
• Setting the region
• Adding an inset to the figure
• Performing grid histogram equalization
• Inset
• Inset map showing a rectangular region

Examples which use 'method' for the tabular and raster data processing functions

• Generate points along great circles
• Create ‘wet-dry’ mask grid
• Blockmean
• Calculating grid gradient and radiance
• Clipping grid values
• Plotting Earth relief
• Color points by categories [see below]
• Multiple colormaps [see below]

API documentation (list is incomplete and was not continued)

• figure.py / psconvert
• table [see below]

---

I am unsure about the usage of the term 'module'. I remember issue #1828 and PR #1858 which are about whether pygmt.Figure.coast is a 'module' or 'method'.

• pygmt.set_display
  • in API doc table: 'module'
• pygmt.grd2cpt
  • in API doc table: 'module'
  • in API doc text: 'method'
• pygmt.makecpt
  • in API doc table: 'module'
  • in API doc text: 'method'
  • in Color points by categories and Multiple colormaps: 'method'

I am definitely not a Python expert! Probably 'module' is inferred from GMT, but the three listed above do not appear to be 'modules' in the Pythonic-sense from xy_module import xy_function (see also second paragraph of issue #1828 (comment)). Maybe it was overlook to also change the API doc table in PR #1858. But why they are 'methods', as changed in PR #1858, despite they do not belong to a class or called on an object? I would be very happy about an explanation for understanding (: In case they are neither 'modules' nor 'methods', it appears that they are 'functions'. Ping @seisman, @maxrjones, @michaelgrund, @willschlitzer (, and @weiji14) for thoughts and help on this, please.

---

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

[maxrjones]

Thanks for working on this!

While there could be exceptions, I think the use of module anywhere in PyGMT's docs likely comes from GMT-centric language and not from any Python-related definition. So unless specifically referring to GMT, these could be updated to "function" or "method".

You are correct that pygmt.set_display, pygmt.grd2cpt, and pygmt.makecpt are functions.

[yvonnefroehlich]

Thanks for working on this!

I am happy to contribute, and at least partly I feel I learn more than I bring to the project 😉

While there could be exceptions, I think the use of module anywhere in PyGMT's docs likely comes from GMT-centric language and not from any Python-related definition. So unless specifically referring to GMT, these could be updated to "function" or "method".

Thanks @maxrjones for your explanation! 🙂

You are correct that pygmt.set_display, pygmt.grd2cpt, and pygmt.makecpt are functions.

I have made the changes in b313a67 as well as 0b13099 and 80339eb. Try to continue with the remaining examples in the next days.

[yvonnefroehlich]

I have now updated all examples listed above.

[seisman]

@yvonnefroehlich Please resolve the conflicts first.

[seisman]

Looks great!

[yvonnefroehlich]

In first_figure.py:

To add to a plot object (fig in this example), the PyGMT module is used as a method on the class. This example will use the pygmt.Figure.coast method, which can be used to create a map without any other methods, modules or external data. The pygmt.Figure.coast method plots the coastlines, borders, and bodies of water using a database that is included in GMT.

I am unsure about the formulations in this part. Should we keep modules in ... other methods, modules or external data ... or change it to functions? PyGMT itself does not have modules in a Pythonic sense. But maybe "modules" is referring to numpy, pandas, etc.?

[seisman]

In first_figure.py:

To add to a plot object (fig in this example), the PyGMT module is used as a method on the class. This example will use the pygmt.Figure.coast method, which can be used to create a map without any other methods, modules or external data. The pygmt.Figure.coast method plots the coastlines, borders, and bodies of water using a database that is included in GMT.

I am unsure about the formulations in this part. Should we keep modules in ... other methods, modules or external data ... or change it to functions? PyGMT itself does not have modules in a Pythonic sense. But maybe "modules" is referring to numpy, pandas, etc.?

I think it originally means "GMT's modules".

Because this is the first PyGMT tutorial and the potential PyGMT users may have never used GMT before, I think it makes very little sense to mention any GMT concepts (e.g., modules) here. So, it's OK to say "without any other methods or external data."

[seisman]

To add to a plot object (fig in this example), the PyGMT module is used as a method on the class.

I also feel that this sentence is a little confusing, because "the PyGMT module" actually means "GMT modules".

[yvonnefroehlich]

In first_figure.py:

To add to a plot object (fig in this example), the PyGMT module is used as a method on the class. This example will use the pygmt.Figure.coast method, which can be used to create a map without any other methods, modules or external data. The pygmt.Figure.coast method plots the coastlines, borders, and bodies of water using a database that is included in GMT.

I am unsure about the formulations in this part. Should we keep modules in ... other methods, modules or external data ... or change it to functions? PyGMT itself does not have modules in a Pythonic sense. But maybe "modules" is referring to numpy, pandas, etc.?

I think it originally means "GMT's modules".

Because this is the first PyGMT tutorial and the potential PyGMT users may have never used GMT before, I think it makes very little sense to mention any GMT concepts (e.g., modules) here. So, it's OK to say "without any other methods or external data."

Done in 3e91e11.

To add to a plot object (fig in this example), the PyGMT module is used as a method on the class.

I also feel that this sentence is a little confusing, because "the PyGMT module" actually means "GMT modules".

I agree. I already have tried to reformulate this sentence, but I was unsure. Thanks @seisman for this explanation! I have made a suggestion in 3db83c8. Of course, I am totally open for changes and improvements on this.

[seisman]

@yvonnefroehlich Reviewing big PRs is more challenging and takes more time than small PRs. I think this PR already has a lot of good changes and should be merged into the main branch after reviewing.

If you think there are still many files that need to be updated, you can open separate PRs later, like what we did in PRs #1857, #1862, #1872.

[yvonnefroehlich]

No worries. We'll give it another round of review when you finish it/

Thanks for your understanding @seisman!

@yvonnefroehlich Reviewing big PRs is more challenging and takes more time than small PRs. I think this PR already has a lot of good changes and should be merged into the main branch after reviewing.

If you think there are still many files that need to be updated, you can open separate PRs later, like what we did in PRs #1857, #1862, #1872.

That's fine for me! 😉 I added the last two changes I had on my list for now.