diff --git a/examples/gallery/maps/choropleth_map.py b/examples/gallery/maps/choropleth_map.py index f1cce8c3014..861bc74a652 100644 --- a/examples/gallery/maps/choropleth_map.py +++ b/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") diff --git a/pygmt/figure.py b/pygmt/figure.py index 591c30b5c85..93f543cdc5e 100644 --- a/pygmt/figure.py +++ b/pygmt/figure.py @@ -421,6 +421,7 @@ def _repr_html_(self) -> str: from pygmt.src import ( # type: ignore[misc] basemap, + choropleth, coast, colorbar, contour, diff --git a/pygmt/src/__init__.py b/pygmt/src/__init__.py index 8905124f917..c0a128f5d1d 100644 --- a/pygmt/src/__init__.py +++ b/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 diff --git a/pygmt/src/choropleth.py b/pygmt/src/choropleth.py new file mode 100644 index 00000000000..039219707a6 --- /dev/null +++ b/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, + )