Add Figure.choropleth to plot choropleth maps

[seisman]

Description of proposed changes

This PR adds the Figure.choropleth method to plot choropleth maps.

Implementations in other packages

• GeoPandas:
  • https://geopandas.org/en/stable/docs/user_guide/mapping.html
  • https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.plot.html
• GeoPlot:
  • https://residentmario.github.io/geoplot/plot_references/plot_reference.html#choropleth
• Plotly:
  • https://plotly.com/python/choropleth-maps/
  • https://plotly.com/python-api-reference/generated/plotly.express.choropleth

Implementation in PyGMT

In PyGMT, Figure.choropleth can be implemented by wrapping the Figure.plot method (see the changes for details). It's API is designed like:

Figure.choropleth(data, fill, **kwargs):

in which,

• data can be :class:geopandas.GeoDataFrame, geo-like objects with __geo_interface or a OGR_GMT file.
• fillcol is the name of the column whose values will be used to assign the colors
• **kwargs are other parameters that can be passed to Figure.plot. Useful parameters are like cmap, pen, transparency and more.

Example

import geopandas as gpd
import pygmt

gdf = gpd.read_file("https://geodacenter.github.io/data-and-lab/data/airbnb.zip")

fig = pygmt.Figure()
pygmt.makecpt(
    cmap="acton",
    series=[gdf["population"].min(), gdf["population"].max(), 10],
    continuous=True,
    reverse=True,
)
fig.choropleth(gdf, fillcol="population", pen="0.3p,gray10")
fig.colorbar(frame=True)
fig.show()

Preview: https://pygmt-dev--2798.org.readthedocs.build/en/2798/api/generated/pygmt.Figure.choropleth.html

[michaelgrund]

Really like this idea, makes it much easier to generate a simple choropleth map. Will wait to continue working on #2796 until this PR is merged.

[github-actions]

Summary of changed images

This is an auto-generated report of images that have changed on the DVC remote

Status	Path
added	pygmt/tests/baseline/test_choropleth.png

Image diff(s)

Details

Added images

• test_choropleth.png

Modified images

Path	Old	New

Report last updated at commit 4b3dc43

[Copilot]

Pull request overview

Adds a new Figure.choropleth convenience method for plotting choropleth maps, along with tests, documentation, and a gallery example.

Changes:

• Introduces pygmt.src.choropleth.choropleth as a thin wrapper around Figure.plot to fill polygons based on a data column, and wires it into Figure and pygmt.src.
• Adds a new gallery example (choropleth_map.py) demonstrating Figure.choropleth with GeoPandas and Natural Earth data.
• Adds a new image-comparison test (test_choropleth) and corresponding baseline image for regression coverage.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
pygmt/src/choropleth.py	Defines the Figure.choropleth wrapper around Figure.plot, with documentation and examples for choropleth maps.
pygmt/src/init.py	Exposes the new choropleth method through the pygmt.src namespace for binding onto Figure.
pygmt/figure.py	Registers choropleth as a Figure method by importing it from pygmt.src.
pygmt/_typing.py	Introduces a GeoLike alias for geopandas.GeoDataFrame and incorporates it into TableLike for geo-related APIs.
pygmt/tests/test_choropleth.py	Adds an MPL image comparison test exercising Figure.choropleth with a GeoPandas world dataset.
pygmt/tests/baseline/test_choropleth.png.dvc	Adds the DVC-tracked baseline image metadata for the new choropleth regression test.
examples/gallery/maps/choropleth_map.py	Updates the gallery example to use Figure.choropleth and documents its usage with GeoPandas data.
doc/api/index.rst	Adds Figure.choropleth to the API autosummary under plotting map elements.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The data parameter is annotated as GeoLike | PathLike, but GeoLike is currently defined only as geopandas.GeoDataFrame while the implementation and surrounding utilities (e.g., helpers.utils.data_kind and helpers.tempfile.tempfile_from_geojson) support any geo-like object implementing __geo_interface__ (including shapely geometries). This mismatch between the type hint and the documented behavior can confuse users and type checkers; consider broadening GeoLike to represent all supported geo-like inputs (e.g., via a protocol/union) or narrowing the docstring to match the actual annotated contract.