Standardize "figure"/"map"/"plot" terminology across codebase

[Copilot]

Inconsistent use of "figure", "map", and "plot" created ambiguity in documentation. Established guidelines: figure = Figure class/object, map = geographic plots only, plot = general term for all plot types (Cartesian, geographic, polar, 3D).

Changes

Documentation structure

• doc/api/index.rst: "Plotting map elements" → "Plotting embellishments"

Examples - non-geographic contexts

• examples/intro/03_figure_element.py: "Map Boundary" → "Plot Boundary"
• examples/projections/nongeo/polar.py: "map limits/width" → "plot limits/width" (12 instances)
• examples/gallery/3d_plots/scatter3d.py: "map dimensions" → "plot dimensions"
• examples/tutorials/basics/text.py: Removed redundant "or map" qualifiers
• examples/tutorials/advanced/configuration.py: "geographical" → "geographic"

Source docstrings

• pygmt/src/{contour,image,text}.py: "on a map" → "on a plot"
• pygmt/src/{plot,plot3d,grdimage}.py: "map region" → "plot region"
• pygmt/helpers/decorators.py: "map boundary/frame" → "plot boundary/frame"
• pygmt/src/rose.py: "map boundary frame" → "plot boundary frame"

Particularly impacts positioning parameters where distinguishing between the plot area (frame interior) and Figure object matters.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>More careful usage of "figure" vs. "map" / "plot"?</issue_title>
<issue_description>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 #2395 (comment) 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 #2395 (comment) 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 29a7bb7.

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:

• Timstamp: Update see PR Figure.timestamp: Improve documentation and gallery example #2434
• Colorbars: Update see PR Minor improvement of docs of gallery example "Colorbars" #2440
• etc.</issue_description>

<agent_instructions>Read through all source files and documentation and fix incorrect usage of figure, map, and plot. More specifically, "map" refers to "geographics plots", "plot" refers to a general plot, and figure refers to the Figure class.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@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](https://matplotlib.org/stable/users/explain/quick_start.html#quick-start), 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.</comment_new>

• Fixes More careful usage of "figure" vs. "map" / "plot"? #2437

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.