Skip to content

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

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

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

Conversation

Copy link
Contributor

Copilot AI commented Feb 14, 2026 •
edited
Loading

Inconsistent use of "map" in general plotting contexts creates ambiguity. The term should be reserved for geographic plots only, with "plot" as the general term.

Changes

Fixed incorrect "map" usage in general plotting functions:

  • pygmt/src/plot.py - Changed "on a map" → "on a plot", "map region" → "plot region"
  • pygmt/src/plot3d.py - Changed "map region" → "plot region"
  • pygmt/src/grdimage.py - Changed "map region" → "plot region"
  • pygmt/src/grdproject.py - Changed "map region large" → "plot region larger"
  • pygmt/src/velo.py - Changed "on a map" → "on a plot"
  • pygmt/src/subplot.py - Changed "main map plotting" → "main plotting", "dimensions of the map" → "dimensions of the plot"

Verified correct "map" usage retained in:

  • Geographic-specific modules: coast, basemap, choropleth, tilemap, scalebar
  • Direction indicators: magnetic_rose, directional_rose
  • Geographic coordinate processing: grdtrack, select, triangulate, x2sys_cross
  • Projection contexts: references to "360-longitude maps" in periodic boundary handling

Terminology

  • map: Geographic plots only
  • plot: General term (Cartesian, geographic, polar, 3D)
  • figure: pygmt.Figure class/object

Total: 6 files, 9 lines changed.

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