Add choropleth support to GeoAxes (#623)

* Add choropleth support to GeoAxes

* Use rc defaults for choropleth

* Move to docstring snippet manager

* Spelling error

* Overlay choropleth edges above borders

Author: cvanelteren

docs/examples/geo/04_choropleth.py

@@ -0,0 +1,55 @@
+"""
+Simple choropleth
+=================
+
+Color country-level values directly on a geographic axes.
+
+Why UltraPlot here?
+-------------------
+UltraPlot now exposes :meth:`~ultraplot.axes.GeoAxes.choropleth`, so you can
+draw country-level thematic maps from plain ISO-style identifiers while using
+the same concise colorbar and formatting API used elsewhere in the library.
+
+Key functions: :py:func:`ultraplot.subplots`, :py:meth:`ultraplot.axes.GeoAxes.choropleth`.
+
+See also
+--------
+* :doc:`Geographic projections </projections>`
+"""
+
+import numpy as np
+
+import ultraplot as uplt
+
+country_values = {
+    "AUS": 1.2,
+    "BRA": 2.6,
+    "IND": 3.4,
+    "ZAF": np.nan,
+}
+
+fig, ax = uplt.subplots(proj="robin", refwidth=4.6)
+
+ax.choropleth(
+    country_values,
+    country=True,
+    cmap="Fire",
+    edgecolor="white",
+    linewidth=0.6,
+    colorbar="r",
+    colorbar_kw={"label": "Index value"},
+    missing_kw={"facecolor": "gray8", "hatch": "//", "edgecolor": "white"},
+)
+
+ax.format(
+    title="Country choropleth",
+    ocean=True,
+    oceancolor="ocean blue",
+    coast=True,
+    borders=True,
+    lonlines=60,
+    latlines=30,
+    labels=False,
+)
+
+fig.show()

docs/projections.py

@@ -325,6 +325,35 @@
     )
 
 
+# %%
+import shapely.geometry as sgeom
+
+fig, ax = uplt.subplots(proj="cyl", refwidth=3.5)
+ax.choropleth(
+    [
+        sgeom.box(-20, -10, -5, 5),
+        sgeom.box(0, -5, 15, 10),
+        sgeom.box(20, -8, 35, 8),
+    ],
+    [1.2, 2.4, 0.7],
+    cmap="Blues",
+    edgecolor="white",
+    linewidth=0.8,
+    colorbar="r",
+    colorbar_kw={"label": "value"},
+)
+ax.format(
+    title="Polygon choropleth",
+    land=True,
+    coast=True,
+    lonlim=(-30, 40),
+    latlim=(-20, 20),
+    labels=True,
+    lonlines=10,
+    latlines=10,
+)
+
+
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_geoformat:
 #