Figure.contour: Adjust processing of arguments passed to the "annotation" and "levels" parameters

[yvonnefroehlich]

Description of proposed changes

This PR aims to adjust the arguments passed to the annotation and levels parameters of Figure.contour:

• input options
  - a fixed interval als float 100 -> 100
  - one level as list: [100] -> 100, (mention the trailing comma)
  - multiple levels as list: [100, 200] -> 100,200
  - no as string: "n" -> n (syntax of GMT 6.5)
• Update docstrings
• Add tests for interval, one level, and multiple levels

Related:

• GMT docs
  • annotation: https://docs.generic-mapping-tools.org/dev/contour.html#a
  • interval: https://docs.generic-mapping-tools.org/dev/contour.html#c
• PR for Figure.grdcontour: Figure.grdcontour: Adjust processing of arguments passed to the "annotation" and "interval" parameters, deprecate "sequence_plus" #3116

Preview: https://pygmt-dev--3116.org.readthedocs.build/en/2706/api/generated/pygmt.Figure.contour.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 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.
• Use underscores (not hyphens) in names of Python files and directories.

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]

Both parameters are very complicated and the current docstrings are too simple.

[yvonnefroehlich]

Both parameters are very complicated and the current docstrings are too simple.

OK, I will try to find time to expand the docstrings for the annotation and the levels or interval parameters of Figure.contour and Figure.grdcontour following the upstream GMT documentation.

[yvonnefroehlich]

For me, the parameters levels and interval appear quite similar / identical. I am wondering whether there is a difference, which explains the different long parameter names.

This is actually related to issue #1042 by @maxrjones. I am wondering whether we should decide on one of these two aliases and deprecate the other one (in a separate PR).

[yvonnefroehlich]

I am still not too happy with the aliases for C of Figure.grdcontour (interval) and of Figure.contour (levels):

• As the behavior / functionality is similar (identical ?) the aliases should be identical. The Julia documentation
  says for both C or cont or contours or levels (https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/grdcontour/index.html#grdcontour, https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/contour/index.html#contour)
• I fell is can be confusing to have an alias interval but pass specific levels, or an alias levels but pass an fixed interval.

So, maybe contours would be a better alias for C (see also https://docs.generic-mapping-tools.org/dev/grdcontour.html#c)?
Maybe we should complete the PRs #2706 and #3116 regarding the allowed input format, and then discuss this in more detail if these two deprecations are worth it?

[seisman]

I am still not too happy with the aliases for C of Figure.grdcontour (interval) and of Figure.contour (levels):

• As the behavior / functionality is similar (identical ?) the aliases should be identical. The Julia documentation
  says for both C or cont or contours or levels (https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/grdcontour/index.html#grdcontour, https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/contour/index.html#contour)
• I fell is can be confusing to have an alias interval but pass specific levels, or an alias levels but pass an fixed interval.

So, maybe contours would be a better alias for C (see also https://docs.generic-mapping-tools.org/dev/grdcontour.html#c)? Maybe we should complete the PRs #2706 and #3116 regarding the allowed input format, and then discuss this in more detail if these two deprecations are worth it?

I agree that these two wrappers should have the same parameter names, but I'm not sure if we should use contours. For reference, the matplotlib one also uses levels: https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.contour.html

[github-actions]

Summary of changed images

This is an auto-generated report of images that have changed on the DVC remote

Status	Path
added	pygmt/tests/baseline/test_contour_interval.png
added	pygmt/tests/baseline/test_contour_multiple_levels.png
added	pygmt/tests/baseline/test_contour_one_level.png

Image diff(s)

Added images

• test_contour_interval.png

• test_contour_multiple_levels.png

• test_contour_one_level.png

Modified images

Path	Old	New

Report last updated at commit 6c24c49

[yvonnefroehlich]

/format

[seisman]

/format