Skip to content

Standardize figure/map/plot terminology in source docstrings#4418

Draft
Copilot wants to merge 12 commits intomainfrom
copilot/update-figure-map-usage
Draft

Standardize figure/map/plot terminology in source docstrings#4418
Copilot wants to merge 12 commits intomainfrom
copilot/update-figure-map-usage

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Feb 14, 2026 •
edited
Loading

  • Review all changes from previous sessions
  • Fix doc/api/index.rst: "Plotting figure elements" → "Plotting embellishments" (consistent with existing gallery and techref terminology)
  • Fix pygmt/src/image.py: "plot it on a plot" → "plots it" (remove awkward phrasing)
  • Fix pygmt/tests/test_image.py: "Place images on map" → "Place images on the figure"
  • Fix pygmt/tests/test_subplot.py: "map frame setting" → "plot frame setting", "all subplot figures" → "all subplot panels", "Plot map elements" → "Plot elements"
  • Comprehensive search performed - all remaining "map" references verified to be in appropriate geographic contexts

Summary of comprehensive review:

All previous changes are correct. Additional issues found and fixed:

  1. doc/api/index.rst: "Plotting figure elements" was wrong twice over - "figure" should refer to the Figure class, and the section lists embellishments (colorbar, legend, scalebar, etc.). Changed to "Plotting embellishments" to match the existing gallery and techref terminology.
  2. image.py: "plot it on a plot" was grammatically awkward (introduced when changing "on a map" to "on a plot"). Fixed to just "plots it."
  3. test_image.py: "Place images on map" - images can be placed on any plot type, not just maps. Fixed to "Place images on the figure."
  4. test_subplot.py: Two docstrings used "map" for non-geographic subplot operations. Fixed to use "plot" terminology.

Verified correct "map" usage in:

  • Geographic functions: coast, basemap, choropleth, tilemap
  • Geographic embellishments: magnetic_rose, directional_rose, scalebar
  • Test functions with geographic projections (Mercator, Mollweide)
  • Python's multiprocessing.Pool.map() in test_session_management.py
  • "map projection" as a technical cartographic term
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:

<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>

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

Copilot AI and others added 2 commits February 14, 2026 10:31
@seisman
Fix incorrect usage of figure/map/plot terminology
8a31ec1 
- Change "plot or map" to "plot" in examples and tutorials
- Change "Map Boundary" to "Plot Boundary" in figure elements example
- Change "Plotting map elements" to "Plotting embellishments" in API docs
- Change "geographical maps" to "geographic maps" for consistency
- Update "map boundary" to "plot boundary" in decorators and rose module

Co-authored-by: seisman <3974108+seisman@users.noreply.github.com>
@seisman
Fix remaining terminology issues
0fc8920 
- Change "geographical tick annotations" to "geographic tick annotations"
- Change "map frame" to "plot frame" in 3D perspective documentation

Co-authored-by: seisman <3974108+seisman@users.noreply.github.com>
Copilot AI changed the title [WIP] Clarify usage of figure vs map and plot Standardize figure/map/plot terminology across documentation Feb 14, 2026
Copilot AI requested a review from seisman February 14, 2026 10:35
@seisman
Fix terminology in scatter3d.py: "map dimensions" → "plot dimensions"
d82c948 
Co-authored-by: seisman <3974108+seisman@users.noreply.github.com>
Copilot AI changed the title Standardize figure/map/plot terminology across documentation Fix terminology: use "plot dimensions" instead of "map dimensions" in 3D scatter example Feb 14, 2026
@seisman
Fix terminology in polar.py and src files: "map" → "plot"
7a58b57 
- examples/projections/nongeo/polar.py: Changed "Set map limits" to "Set plot limits" and "Set map width" to "Set plot width" (12 instances)
- pygmt/src/contour.py: Changed "on a map" to "on a plot"
- pygmt/src/image.py: Changed "on a map" to "on a plot"
- pygmt/src/text.py: Changed "on the map" to "on the plot" and "of the map" to "of the plot"

Co-authored-by: seisman <3974108+seisman@users.noreply.github.com>
Copilot AI changed the title Fix terminology: use "plot dimensions" instead of "map dimensions" in 3D scatter example Standardize "figure"/"map"/"plot" terminology across codebase Feb 14, 2026
@seisman
Fix terminology in plot.py, plot3d.py, and grdimage.py: "map region" …
76adc44 
…→ "plot region"

- pygmt/src/plot.py line 199: Changed "clipped to the map region" to "clipped to the plot region"
- pygmt/src/plot3d.py line 174: Changed "clipped to the map region" to "clipped to the plot region"
- pygmt/src/grdimage.py line 72: Changed "select a map region" to "select a plot region"

Co-authored-by: seisman <3974108+seisman@users.noreply.github.com>
Copilot AI and others added 2 commits February 25, 2026 03:28
@seisman
Fix terminology in grdproject, plot, and velo: "map" → "plot"
90dd1f0 
Deep search revealed additional terminology issues:
- pygmt/src/grdproject.py: "map region large" → "plot region larger" (also fixed typo)
- pygmt/src/plot.py: "on a map" → "on a plot"
- pygmt/src/velo.py: "on a map" → "on a plot"

Co-authored-by: seisman <3974108+seisman@users.noreply.github.com>
@seisman
Fix terminology in subplot.py: "map" → "plot" in general context
368a501 
Deep search found three more instances in subplot.py where "map" was used in contexts that apply to all plot types (not just geographic maps):
- Line 248: "main map plotting" → "main plotting"
- Line 378: "dimensions of the map" → "dimensions of the plot"
- Line 410: "main map plotting" → "main plotting"

Co-authored-by: seisman <3974108+seisman@users.noreply.github.com>
Copilot AI changed the title Standardize "figure"/"map"/"plot" terminology across codebase Standardize figure/map/plot terminology in source docstrings Feb 25, 2026
@seisman
Final review: fix remaining terminology issues
3f8c9a8 
- doc/api/index.rst: "Plotting figure elements" → "Plotting embellishments" (consistent with gallery and techref usage)
- pygmt/src/image.py: "plot it on a plot" → "plots it" (fix awkward phrasing)
- pygmt/tests/test_image.py: "Place images on map" → "Place images on the figure"
- pygmt/tests/test_subplot.py: "map frame setting" → "plot frame setting", "all subplot figures" → "all subplot panels", "Plot map elements" → "Plot elements"

Agent-Logs-Url: https://github.com/GenericMappingTools/pygmt/sessions/ec6d8067-efa4-4bd0-ad87-85456d70041c

Co-authored-by: seisman <3974108+seisman@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@seisman seisman Awaiting requested review from seisman

At least 1 approving review is required to merge this pull request.

Assignees

@seisman seisman

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

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

2 participants

@seisman