More careful usage of "figure" vs. "map" / "plot"?

[yvonnefroehlich]

Currently, "figure" and "map" / "plot" more or less used interchangeable. However, there can be a relevant difference, mostly in the context of setting the anchor point (position parameter). Further, "figure" also refers more to the figure object / instance created via pygmt.Figure().

First dicussed in https://github.com/GenericMappingTools/pygmt/pull/2395#discussion_r1131261305 by @michaelgrund:

In my opinion "figure" is not correct here, since the whole object is the figure, including the area outside the map frame where the colorbar is placed.

and https://github.com/GenericMappingTools/pygmt/pull/2395#discussion_r1131330064 by @yvonnefroehlich:

I see your point. My intention to change it was that the generated figure is no geographical map. Maybe "plot" would serve as a more general term? But I am not sure whether there is a clear differentiation between "plot" and "figure". Thus, I changed it back to "map" in commit https://github.com/GenericMappingTools/pygmt/commit/29a7bb76eed7636ee74d126f54327be04d0040f1.

This is a bit related to issue #2026 and maybe can be included in the tutorial added by @JingHuiTong in PR #2383?

This impacts mainly on the docstrings as well as gallery examples and tutorials:

• [x] Timstamp: Update see PR #2434
• [x] Colorbars: Update see PR #2440
• [ ] etc.

[jhtong33]

I try to describe this issue in PR #2383. Could you help the documentation (pygmt.Figure) more clear?

[seisman]

Looking at the Matplotlib tutorial, here is my understanding/preference:

• plot: A general term which can describe Cartesian, geographic, polar, or 3D "plots".
• map should be limited to a geographic plot.
• figure refers to the pygmt.Figure object.