Figure.choropleth: Refactor using low-level sessions and virtualfiles

pygmt/src/choropleth.py

@@ -2,27 +2,61 @@
 choropleth - Plot a choropleth map.
 """
 
+from collections.abc import Sequence
+from typing import Literal
+
 from pygmt._typing import GeoLike, PathLike
+from pygmt.alias import Alias, AliasSystem
+from pygmt.clib import Session
+from pygmt.helpers import build_arg_list, fmt_docstring
+from pygmt.params import Axis, Frame
 
 __doctest_skip__ = ["choropleth"]
 
 
-def choropleth(
+@fmt_docstring
+def choropleth(  # noqa: PLR0913
     self,
     data: GeoLike | PathLike,
     column: str,
     cmap: str | bool = True,
-    **kwargs,
+    intensity: float | None = None,
+    pen: str | None = None,
+    no_clip: bool = False,
+    projection: str | None = None,
+    region: Sequence[float | str] | str | None = None,
+    frame: Frame | Axis | Literal["none"] | str | Sequence[str] | bool = False,
+    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
+    | bool = False,
+    panel: int | Sequence[int] | bool = False,
+    perspective: float | Sequence[float] | str | bool = False,
+    transparency: float | None = None,
 ):
     """
     Plot a choropleth map.
 
-    This method is a thin wrapper around :meth:`pygmt.Figure.plot` that sets the
-    appropriate parameters for creating a choropleth map by filling polygons based on
-    values in a specified data column. It requires the input data to be a geo-like
-    Python object that implements ``__geo_interface__`` (e.g. a
-    :class:`geopandas.GeoDataFrame`), or an OGR_GMT file containing the geometry and
-    data to plot.
+    This method fills polygons based on values in a specified data column. It requires
+    the input data to be a geo-like Python object that implements ``__geo_interface__``
+    (e.g. a :class:`geopandas.GeoDataFrame`), or an OGR_GMT file containing the
+    geometry and data to plot.
+
+    **Aliases:**
+
+    .. hlist::
+       :columns: 3
+
+       - B = frame
+       - C = cmap
+       - I = intensity
+       - J = projection
+       - R = region
+       - N = no_clip
+       - W = pen
+       - V = verbose
+       - a = column
+       - c = panel
+       - p = perspective
+       - t = transparency
 
     Parameters
     ----------
@@ -35,8 +69,19 @@ def choropleth(
     cmap
         The CPT to use for filling the polygons. If set to ``True``, the current CPT
         will be used.
-    **kwargs
-        Additional keyword arguments passed to :meth:`pygmt.Figure.plot`.
+    intensity
+        The intensity (nominally in the ±1 range) to modulate the fill color by
+        simulating illumination [Default is no illumination].
+    no_clip
+        Do **not** clip polygons that fall outside the frame boundaries.
+    $pen
+    $projection
+    $region
+    $frame
+    $verbose
+    $panel
+    $perspective
+    $transparency
 
     Examples
     --------
@@ -46,14 +91,36 @@ def choropleth(
     ...     "https://naciscdn.org/naturalearth/110m/cultural/ne_110m_admin_0_countries.zip"
     ... )
     >>> world["POP_EST"] *= 1e-6  # Population in millions
-
+    >>>
     >>> fig = pygmt.Figure()
     >>> fig.basemap(region=[-19.5, 53, -38, 37.5], projection="M15c", frame=True)
     >>> pygmt.makecpt(cmap="bilbao", series=(0, 270, 10), reverse=True)
     >>> fig.choropleth(world, column="POP_EST", pen="0.3p,gray10")
     >>> fig.colorbar(frame=True)
     >>> fig.show()
     """
-    self.plot(
-        data=data, close=True, fill="+z", cmap=cmap, aspatial=f"Z={column}", **kwargs
+    self._activate_figure()
+
+    aliasdict = AliasSystem(
+        C=Alias(cmap, name="cmap"),
+        I=Alias(intensity, name="intensity"),
+        N=Alias(no_clip, name="no_clip"),
+        W=Alias(pen, name="pen"),
+        a=Alias(f"Z={column}", name="column"),
+    ).add_common(
+        B=frame,
+        J=projection,
+        R=region,
+        V=verbose,
+        c=panel,
+        p=perspective,
+        t=transparency,
     )
+    # Force -G+z and -L to be set for choropleth
+    aliasdict.update({"G": "+z", "L": True})
+
+    with Session() as lib:
+        with lib.virtualfile_in(check_kind="vector", data=data) as vintbl:
+            lib.call_module(
+                module="plot", args=build_arg_list(aliasdict, infile=vintbl)
+            )