Choropleth Maps
===============

:class:`~mappyng.ChoroplethLayer` classifies a numeric column using
mapclassify and draws filled polygons.  The legend is drawn automatically
below the main map.

.. code-block:: python

   import geopandas as gpd
   from mappyng import Map, BasemapLayer, ChoroplethLayer

   gdf = gpd.read_file("departements_population.gpkg")

   m = Map(gdf, width=800, height="auto")
   m.add(BasemapLayer())
   m.add(ChoroplethLayer(
       gdf,
       column="pop",
       cmap="YlOrRd",
       method="Quantiles",
       num_classes=5,
       stroke_width=0.15,
       legend={
           "title": "Population",
           "decimals": 0,
           "orientation": "vertical",
       },
   ))
   m.render("choropleth.svg")

Layer parameters
----------------

These are passed as keyword arguments to ``ChoroplethLayer(gdf, ...)``.

.. list-table::
   :header-rows: 1
   :widths: 22 15 63

   * - Key
     - Default
     - Description
   * - ``column``
     - required
     - Numeric column to classify.
   * - ``cmap``
     - ``"YlOrRd"``
     - Colormap name (``"YlOrRd"``, ``"Blues"``, ``"Greens"``, ``"Reds"``,
       ``"RdYlGn"``) or a list of hex strings of length ``num_classes``.
   * - ``method``
     - ``"FisherJenks"``
     - Classification scheme: ``"EqualInterval"``, ``"Quantiles"``,
       ``"FisherJenks"``, ``"Q6"``, ``"StdMean"``, or a list of custom
       break values (length ``num_classes + 1``).
   * - ``num_classes``
     - 5
     - Number of classes (4-7).  Ignored when ``method`` is a list.
   * - ``stroke``
     - from style
     - Polygon outline color.
   * - ``stroke_width``
     - from style
     - Polygon outline width in SVG px.
   * - ``dissolve``
     - ``False``
     - Dissolve polygons by class before rendering (reduces SVG size).
   * - ``on_zoom``
     - ``True``
     - Render this layer on the zoom viewport.
   * - ``on_cartouches``
     - ``True``
     - Render this layer on cartouche viewports.
   * - ``legend``
     - ``None``
     - Legend sub-config dict.  See tables below.

Legend parameters (``legend`` sub-dict)
----------------------------------------

Shared fields (all legend types)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Key
     - Default
     - Description
   * - ``title``
     - ``None``
     - Legend title text.
   * - ``subtitle``
     - ``None``
     - Subtitle rendered below the title.
   * - ``title_fontsize``
     - from style
     - Title font size.
   * - ``title_fontcolor``
     - from style
     - Title font color.
   * - ``title_fontweight``
     - from style
     - Title font weight (e.g. ``"bold"``).
   * - ``title_fontfamily``
     - from style
     - Title font family.
   * - ``title_max_chars``
     - 35
     - Characters per line before title wraps.
   * - ``title_offset_x``
     - 0.0
     - Additional horizontal offset for title (SVG px).
   * - ``title_offset_y``
     - 0.0
     - Additional vertical offset for title (SVG px).
   * - ``fontsize``
     - from style
     - Label font size.
   * - ``fontcolor``
     - from style
     - Label font color.
   * - ``fontweight``
     - from style
     - Label font weight.
   * - ``fontfamily``
     - from style
     - Label font family.
   * - ``hatch_style``
     - from style
     - SVG hatch fill for swatches: ``"///"``, ``"\\\\"``, ``"xxx"``,
       ``"..."``, ``"|||"``, ``"---"``.
   * - ``hatch_color``
     - from style
     - Hatch line color.
   * - ``spacing``
     - 0.01
     - Extra vertical offset added to auto-position (fraction of content height).
   * - ``position``
     - ``None``
     - Manual position ``{"x": frac, "y": frac}`` (0,0 = top-left, 1,1 = bottom-right).
   * - ``frame``
     - ``None``
     - Background frame: ``False`` = none, ``True`` = default frame,
       dict = overrides (see :ref:`legend-frame`).

Choropleth-specific fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Key
     - Default
     - Description
   * - ``decimals``
     - 1
     - Decimal places for class boundary labels.
   * - ``orientation``
     - ``"horizontal"``
     - Legend layout: ``"horizontal"`` or ``"vertical"``.
   * - ``swatch_size``
     - ``None``
     - Global width override for all swatches (horizontal **and** vertical
       modes).  Height is always derived as ``swatch_size / phi`` (golden
       ratio).  Overrides ``swatch_width`` and ``vertical_swatch_width``.
       Example: ``"swatch_size": 40``.
   * - ``swatch_width``
     - 30
     - Color swatch width in horizontal mode (SVG px).
   * - ``swatch_height``
     - auto
     - Swatch height in horizontal mode.
       Defaults to ``swatch_width / phi`` (golden ratio).
   * - ``swatch_spacing``
     - 2
     - Gap between swatches (SVG px).
   * - ``label_rotation``
     - 0
     - Label rotation in degrees.
   * - ``label_position``
     - ``"border"``
     - ``"border"``, n+1 labels at swatch edges.
       ``"center"``, n labels centered inside each swatch.
   * - ``label_format``
     - ``"value"``
     - With ``label_position="center"``: ``"value"`` (lower bound) or
       ``"range"`` (``[min, max]`` interval).
   * - ``label_anchor``
     - ``"middle"``
     - SVG text-anchor for rotated labels: ``"middle"`` or ``"end"``.
   * - ``label_margin``
     - 4
     - Gap between swatch bottom and label baseline (SVG px).
   * - ``nodata_label``
     - ``"N/A"``
     - Label for missing-value swatch.
   * - ``nodata_gap``
     - 10
     - Gap between last class swatch and N/A swatch (SVG px).
   * - ``nodata_label_gap``
     - 4
     - Gap between N/A swatch right edge and its label (SVG px).
   * - ``vertical_swatch_width``
     - 16
     - Swatch width in vertical mode (SVG px).
   * - ``vertical_swatch_height``
     - 12
     - Swatch height in vertical mode (SVG px).
   * - ``vertical_label_gap``
     - 6
     - Gap between swatch and label in vertical mode (SVG px).
   * - ``labels``
     - ``None``
     - Custom label list (length == num_classes) replacing auto-generated labels.

.. _legend-frame:

Legend frame fields (``frame`` dict)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Key
     - Default
     - Description
   * - ``fill``
     - ``"white"``
     - Frame background color.
   * - ``fill_opacity``
     - 0.9
     - Frame background opacity.
   * - ``stroke``
     - ``"#cccccc"``
     - Frame border color.
   * - ``stroke_width``
     - 0.5
     - Frame border width (SVG px).
   * - ``border_radius``
     - 4
     - Frame corner radius (SVG px).
   * - ``padding``
     - 8
     - Inner padding between content and frame edge (SVG px).
   * - ``shadow``
     - ``False``
     - Add drop shadow behind the frame.
   * - ``shadow_dx`` / ``shadow_dy``
     - 2 / 2
     - Shadow offset (SVG px).
   * - ``shadow_blur``
     - 4
     - Shadow blur radius (SVG px).
   * - ``shadow_opacity``
     - 0.3
     - Shadow opacity.