POC: Add Figure.choropleth to plot choropleth maps

examples/gallery/maps/choropleth_map.py

@@ -2,15 +2,14 @@
 Choropleth map
 ==============
 
-The :meth:`pygmt.Figure.plot` method allows us to plot geographical data such as
-polygons which are stored in a :class:`geopandas.GeoDataFrame` object. Use
-:func:`geopandas.read_file` to load data from any supported OGR format such as a
+The :meth:`pygmt.Figure.choropleth` method allows us to plot geographical data such as
+polygons which are stored in a :class:`geopandas.GeoDataFrame` object or a OGR_GMT file.
+Use :func:`geopandas.read_file` to load data from any supported OGR formats such as a
 shapefile (.shp), GeoJSON (.geojson), geopackage (.gpkg), etc. You can also use a full
 URL pointing to your desired data source. Then, pass the :class:`geopandas.GeoDataFrame`
-as an argument to the ``data`` parameter of :meth:`pygmt.Figure.plot`, and style the
-geometry using the ``pen`` parameter. To fill the polygons based on a corresponding
-column you need to set ``fill="+z"`` as well as select the appropriate column using the
-``aspatial`` parameter as shown in the example below.
+as an argument to the ``data`` parameter of :meth:`pygmt.Figure.choropleth`, and style
+the geometry using the ``pen`` parameter. To fill the polygons based on a corresponding
+column you need to specify the colum name to the ``column`` parameter.
 """
 
 # %%
@@ -43,14 +42,8 @@
 )
 
 # Next, we plot the polygons and fill them using the defined colormap. The target column
-# is defined by the aspatial parameter.
-fig.plot(
-    data=gdf,
-    pen="0.3p,gray10",
-    fill="+z",
-    cmap=True,
-    aspatial="Z=population",
-)
+# is specified by the `column` parameter.
+fig.choropleth(data=gdf, column="population", pen="0.3p,gray10", cmap=True)
 
 # Add colorbar legend.
 fig.colorbar(frame="x+lPopulation", position="jML+o-0.5c+w3.5c/0.2c")

pygmt/figure.py

@@ -421,6 +421,7 @@ def _repr_html_(self) -> str:
 
     from pygmt.src import (  # type: ignore[misc]
         basemap,
+        choropleth,
         coast,
         colorbar,
         contour,

pygmt/src/__init__.py

@@ -5,6 +5,7 @@
 from pygmt.src.basemap import basemap
 from pygmt.src.binstats import binstats
 from pygmt.src.blockm import blockmean, blockmedian, blockmode
+from pygmt.src.choropleth import choropleth
 from pygmt.src.coast import coast
 from pygmt.src.colorbar import colorbar
 from pygmt.src.config import config

pygmt/src/choropleth.py

@@ -0,0 +1,29 @@
+"""
+choropleth - Plot a choropleth map.
+"""
+
+import contextlib
+
+with contextlib.suppress(ImportError):
+    import geopandas as gpd
+
+
+def choropleth(self, data: gpd.GeoDataFrame, column: str, **kwargs):
+    """
+    Plot a choropleth map.
+
+    Parameters
+    ----------
+    data
+        A :class:`geopandas.DataFrame` object or a OGR_GMT file containing the geometry
+        and data to plot.
+    column
+        The name of the data column to use for the fill.
+    """
+    self.plot(
+        data=data,
+        close=True,
+        fill="+z",
+        aspatial=f"Z={column}",
+        **kwargs,
+    )