Complete documentation of grdimage #620

weiji14 · 2020-09-20T03:37:05Z

Description of proposed changes

Time to put an end to all the noise about grdimage not being properly documented! To be fair, the documentation at https://www.pygmt.org/v0.2.0/api/generated/pygmt.Figure.grdimage.html is pretty embarrasing, considering that grdimage is one of the more widely used functions! For reference, upstream GMT docs is at https://docs.generic-mapping-tools.org/6.1/grdimage.html

Mentioned before at #364 (comment) and https://forum.generic-mapping-tools.org/t/grdgradient-in-pygmt/723/12.

Live documentation preview is at https://pygmt-git-grdimage-documentallargs.gmt.vercel.app/api/generated/pygmt.Figure.grdimage.html#pygmt.Figure.grdimage.

TODO:

Arguments/Aliases to document (see also https://www.generic-mapping-tools.org/GMT.jl/latest/#GMT.grdimage):

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.

Add automatic docstrings for frame (B), cmap (C), projection (J), region (R), timestamp (U), verbose (V), and interpolation (n). Also removed alias pen (W) that actually doesn't work.

Copied from https://docs.generic-mapping-tools.org/6.1/grdimage.html, swapping out short command-line arguments for long aliases.

…_all_args

pygmt/base_plotting.py

weiji14 · 2020-09-21T06:10:51Z

Ok, ready for review, and preview at https://pygmt-git-grdimage-documentallargs.gmt.vercel.app/api/generated/pygmt.Figure.grdimage.html#pygmt.Figure.grdimage! Best to take a closer look, I'm pretty sure I've messed up on some formatting. Also no rush to do it today since it's getting late.

This also helps with #618, documenting the fact that shading="intensfile" works. Will deal with xarray.DataArray inputs (a Python specific feature) separately another time.

pygmt/base_plotting.py

Co-authored-by: Dongdong Tian <[email protected]>

seisman · 2020-09-22T09:53:59Z

pygmt/base_plotting.py

+        `grdmath` or `grdhisteq`. A third alternative is available when GMT is
+        build with GDAL support. Pass **image** which can be an image file
+        (geo-referenced or not). In this case the image can optionally be


It reads awkwardly.

Suggested change

`grdmath` or `grdhisteq`. A third alternative is available when GMT is

build with GDAL support. Pass **image** which can be an image file

(geo-referenced or not). In this case the image can optionally be

`grdmath` or `grdhisteq`. A third alternative is available when GMT is

build with GDAL support. Pass **image** which can be an image file

(geo-referenced or not). In this case the image can optionally be

Agree that this could be worded better, currently it's just copied from upstream GMT at https://github.com/GenericMappingTools/gmt/blob/8c0b548e52938f91bfb15f47f27d023488003ef8/doc/rst/source/grdimage_common.rst_#L14-L16. Maybe we should take out the grdgradient, grdmath and grdhisteq parts since they're not wrapped in PyGMT yet?

I'm afraid we may forget to add them back when the wrappers are available.

Maybe keep them for now, better to over-document than not. Doubt we'll see grdmath anytime soon (who uses Reverse Polish notation?!!), but grdgradient would definitely come, and grdhisteq will be a nice one for stretching colormaps.

Yes, I agree.

pygmt/base_plotting.py

weiji14 · 2020-09-22T21:17:36Z

pygmt/base_plotting.py

+        `grdmath` or `grdhisteq`. A third alternative is available when GMT is
+        build with GDAL support. Pass **image** which can be an image file
+        (geo-referenced or not). In this case the image can optionally be


Agree that this could be worded better, currently it's just copied from upstream GMT at https://github.com/GenericMappingTools/gmt/blob/8c0b548e52938f91bfb15f47f27d023488003ef8/doc/rst/source/grdimage_common.rst_#L14-L16. Maybe we should take out the grdgradient, grdmath and grdhisteq parts since they're not wrapped in PyGMT yet?

weiji14 · 2020-09-22T21:18:22Z

pygmt/base_plotting.py

+        (geo-referenced or not). In this case the image can optionally be
+        illuminated with the file provided via the *shading* option. Here, if
+        image has no coordinates then those of the intensity file will be used.


What do you think about taking out this sentence about image, related to the change at https://github.com/GenericMappingTools/pygmt/pull/620/files#r492612750.

What do you think about taking out this sentence about image, related to the change at https://github.com/GenericMappingTools/pygmt/pull/620/files#r492612750.

The changes are big. It's unclear to me what you mean by "taking out this sentence about image"?

Oops, wrong link. Should be #620 (comment). The part where we took out grid | image.

The reason to take out grid | image is, it's a little unclear what grid | image means, and for the grid argument, we already mention that grid could be a image:

The file name or a DataArray containing the input 2-D gridded data set or image to be plotted

Yes, agree that taking grid | image is ok. But would this lead to confusion about this sentence:

Pass **image** which can be an image file (geo-referenced or not). In this case the image can optionally be illuminated with the file provided via the *shading* option. Here, if image has no coordinates then those of the intensity file will be used.

I suppose we could just keep it to keep it in line with upstream GMT?

That's why I said these sentences don't read well in #620 (comment).

Perhaps we can change:

A third alternative is available when GMT is build with GDAL support. Pass image which can be an image file (geo-referenced or not). In this case the image can optionally be illuminated with the file provided via the -I option. Here, if image has no coordinates then those of the intensity file will be used.

to

If GMT is built with GDAL support, grid can be an image file (geo-referenced or not). In this case the image can optionally be illuminated with the file provided via the -I option. Here, if image has no coordinates then those of the intensity file will be used.

Looks good enough (mentioning that image can be used with GDAL support). I'll commit the change.

Co-Authored-By: Dongdong Tian <[email protected]>

seisman · 2020-09-22T22:54:55Z

pygmt/base_plotting.py

+            grid via a call to `grdgradient`; append **+a** \\ *azimuth*,
+            **+n** \\ *args*, and **+m** \\ *ambient* to specify azimuth,


There should be no spaces between modifier and value:

Suggested change

grid via a call to `grdgradient`; append **+a** \\ *azimuth*,

**+n** \\ *args*, and **+m** \\ *ambient* to specify azimuth,

grid via a call to `grdgradient`; append **+a**\\ *azimuth*,

**+n**\\ *args*, and **+m**\\ *ambient* to specify azimuth,

Are you sure we need double back-slashes?

Good catch. Single backslash would result in a flake8 error W605 invalid escape sequence '\ '

Single backslash would result in a flake8 error W605 invalid escape sequence '\ '

Double backslashes in ReST syntax doesn't give what we want if they're not in docstring: http://rst.ninjs.org/#KiorYSoqXFwgKmF6aW11dGgq

Why does flake8 check ReST syntax? Is it a flake8 bug? Or can we make flake8 ignore it for ReST strings?

Anyway, the documentation looks good now. We may see if we can avoid double backslashes in the future.

Double backslashes in ReST syntax doesn't give what we want if they're not in docstring: http://rst.ninjs.org/#KiorYSoqXFwgKmF6aW11dGgq

The double backslash is needed for Python, the alternative would be to use a raw string (e.g. r" **+n**\ *args* "). We came across this at #525 (comment), might be good if we can standardize this in our CONTRIBUTING.md document (open an issue?).

Anyways, the rendered version looks fine:

Why does flake8 check ReST syntax? Is it a flake8 bug? Or can we make flake8 ignore it for ReST strings?

A quick search yields https://github.com/kataev/flake8-rst, but I haven't tried it, and don't know if it does what we want.

GMT uses singe backslash syntax like **+a**\ *azimuth*. If we copy documentation from GMT, then I expect we will see the same warning often.

I'll open up an issue for this to continue the discussion :)

Co-Authored-By: Dongdong Tian <[email protected]>

weiji14 · 2020-09-22T23:31:30Z

Hmm, there's a strange failure on the Ubuntu Python 3.6 test at https://github.com/GenericMappingTools/pygmt/pull/620/checks?check_run_id=1152171757 with a missing earth_relief grid. I'll re-run just to be sure before merging.

Document common aliases for grdimage

b47ab35

Add automatic docstrings for frame (B), cmap (C), projection (J), region (R), timestamp (U), verbose (V), and interpolation (n). Also removed alias pen (W) that actually doesn't work.

weiji14 added the documentation Improvements or additions to documentation label Sep 20, 2020

Alias dpi (E) for grdimage

4c352c0

vercel bot temporarily deployed to Preview September 20, 2020 04:13 Inactive

weiji14 added 2 commits September 20, 2020 16:17

Copy grdimage long description from GMT manpage

b7029c5

Copied from https://docs.generic-mapping-tools.org/6.1/grdimage.html, swapping out short command-line arguments for long aliases.

Alias monochrome (M), noclip (N) and nan_alpha (Q) for grdimage

14ba332

weiji14 force-pushed the grdimage/document_all_args branch from 41b9e01 to 14ba332 Compare September 20, 2020 04:18

vercel bot temporarily deployed to Preview September 20, 2020 04:18 Inactive

weiji14 added this to the 0.2.1 milestone Sep 20, 2020

weiji14 added 4 commits September 21, 2020 09:14

Merge remote-tracking branch 'upstream/master' into grdimage/document…

740c980

…_all_args

Alias img_out (A) and img_in (D) for grdimage

4584c32

Alias bit_color (G) for grdimage

4c1fcb2

Remove mention of RGB grid inputs, following GMT 6.2.0 grdimage docs

d2b6997

vercel bot temporarily deployed to Preview September 20, 2020 22:11 Inactive

weiji14 commented Sep 20, 2020

View reviewed changes

pygmt/base_plotting.py Show resolved Hide resolved

seisman reviewed Sep 20, 2020

View reviewed changes

pygmt/base_plotting.py Show resolved Hide resolved

pygmt/base_plotting.py Outdated Show resolved Hide resolved

pygmt/base_plotting.py Outdated Show resolved Hide resolved

This was referenced Sep 20, 2020

Add common alias cores (x) for grdimage and other multi-threaded modules #625

Merged

Add common aliases xshift (X) and yshift (Y) #624

Merged

weiji14 added 4 commits September 21, 2020 15:56

Merge branch 'master' into grdimage/document_all_args

42e2b28

Change grdimage aliases to no_clip (N) and nan_transparent (Q)

8817749

Fix indentation of bit_color docstring

581968a

Document shading (I) for grdimage

a0771e6

vercel bot temporarily deployed to Preview September 21, 2020 04:12 Inactive

weiji14 mentioned this pull request Sep 21, 2020

Add common alias perspective (p) for plotting 3D illustrations #627

Merged

5 tasks

Merge branch 'master' into grdimage/document_all_args

8ad8d7c

vercel bot temporarily deployed to Preview September 21, 2020 05:47 Inactive

weiji14 marked this pull request as ready for review September 21, 2020 06:05

seisman reviewed Sep 22, 2020

View reviewed changes

pygmt/base_plotting.py Outdated Show resolved Hide resolved

pygmt/base_plotting.py Outdated Show resolved Hide resolved

pygmt/base_plotting.py Outdated Show resolved Hide resolved

pygmt/base_plotting.py Outdated Show resolved Hide resolved

Fix grdimage docstring formatting

3b14a0e

Co-authored-by: Dongdong Tian <[email protected]>

vercel bot temporarily deployed to Preview September 22, 2020 05:08 Inactive

Fix flake8 issue with >79 chars and backslash

ccf6c1d

vercel bot temporarily deployed to Preview September 22, 2020 05:19 Inactive

seisman reviewed Sep 22, 2020

View reviewed changes

weiji14 commented Sep 22, 2020

View reviewed changes

vercel bot temporarily deployed to Preview September 22, 2020 21:28 Inactive

Properly bold and italicize some more arguments and remove grid | image

924e5a8

Co-Authored-By: Dongdong Tian <[email protected]>

weiji14 force-pushed the grdimage/document_all_args branch from f3aa3f7 to 924e5a8 Compare September 22, 2020 21:30

vercel bot temporarily deployed to Preview September 22, 2020 21:30 Inactive

Improve explanation of image inputs into grdimage

6f0c34a

Co-Authored-By: Dongdong Tian <[email protected]>

vercel bot temporarily deployed to Preview September 22, 2020 22:29 Inactive

seisman reviewed Sep 22, 2020

View reviewed changes

Trim whitespace between +a azimuth and others

6b6e63a

Co-Authored-By: Dongdong Tian <[email protected]>

vercel bot temporarily deployed to Preview September 22, 2020 23:06 Inactive

seisman approved these changes Sep 22, 2020

View reviewed changes

weiji14 merged commit 593ca1a into master Sep 23, 2020

weiji14 deleted the grdimage/document_all_args branch September 23, 2020 00:07

weiji14 mentioned this pull request Sep 23, 2020

How to reproduce original GMT arguments in PyGMT documentation #631

Closed

seisman mentioned this pull request Oct 22, 2020

Add "no_clip" to plot, text, contour and meca #661

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Complete documentation of grdimage #620

Complete documentation of grdimage #620

weiji14 commented Sep 20, 2020 •

edited

Loading

weiji14 commented Sep 21, 2020

seisman Sep 22, 2020

weiji14 Sep 22, 2020

seisman Sep 22, 2020

weiji14 Sep 22, 2020

seisman Sep 22, 2020

weiji14 Sep 22, 2020

weiji14 Sep 22, 2020

seisman Sep 22, 2020

weiji14 Sep 22, 2020

seisman Sep 22, 2020 •

edited

Loading

weiji14 Sep 22, 2020

seisman Sep 22, 2020

weiji14 Sep 22, 2020

seisman Sep 22, 2020

weiji14 Sep 22, 2020 •

edited

Loading

seisman Sep 22, 2020

seisman Sep 22, 2020

weiji14 Sep 22, 2020 •

edited

Loading

seisman Sep 22, 2020

weiji14 Sep 23, 2020

weiji14 commented Sep 22, 2020

		grid via a call to `grdgradient`; append +a \\ azimuth,
		+n \\ args, and +m \\ ambient to specify azimuth,

Complete documentation of grdimage #620

Complete documentation of grdimage #620

Conversation

weiji14 commented Sep 20, 2020 • edited Loading

weiji14 commented Sep 21, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seisman Sep 22, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weiji14 Sep 22, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weiji14 Sep 22, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weiji14 commented Sep 22, 2020

weiji14 commented Sep 20, 2020 •

edited

Loading

seisman Sep 22, 2020 •

edited

Loading

weiji14 Sep 22, 2020 •

edited

Loading

weiji14 Sep 22, 2020 •

edited

Loading