Draw a Choropleth Map — draw_choropleth • rtemis.draw

Render a choropleth map with MapLibre GL: regions shaded by a value, joined to vendored administrative boundaries (countries by ISO-A3, US states / counties by FIPS). No basemap tiles – boundaries render on the themed background, with light/dark auto-detection like the rest of draw_*.

Usage

draw_choropleth(
  x,
  location,
  value,
  resolution = c("country", "state", "county"),
  tooltip = NULL,
  value_label = NULL,
  classification = "quantile",
  colormap = "blues",
  num_classes = 5,
  opacity = 1,
  show_boundaries = TRUE,
  outline_width = 0.2,
  show_legend = TRUE,
  legend_position = "bottom-right",
  tooltip_position = "top-right",
  title = NULL,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL
)

Arguments

x: Data frame: One row per region.
location: Character: Name of the column holding the location key (FIPS / ISO / name).
value: Character: Name of the numeric column to color by.
resolution: Character {"country", "state", "county"}: Administrative resolution selecting the geometry and the join key.
tooltip: Optional Character: Names of extra columns to show in the hover tooltip, in order.
value_label: Optional Character: Label for the value column in the legend / tooltip; defaults to value.
classification: Character {"quantile", "equal", "jenks"}: Class-break method. "quantile" (equal counts), "equal" (equal intervals), or "jenks" (natural breaks).
colormap: Character: Color ramp. One of the sequential schemes "blues", "viridis", "ylorrd", "greens", "magma", or the diverging schemes "rdbu", "rdylgn", "spectral", "brbg".
num_classes: Numeric [2, 12]: Number of color classes.
opacity: Numeric [0, 1]: Region fill opacity.
show_boundaries: Logical: Whether to draw region outlines.
outline_width: Numeric [0, Inf): Region outline width in pixels.
show_legend: Logical: Whether to show the legend.
legend_position: Character {"top-left", "top-right", "bottom-left", "bottom-right"}: Legend corner.
tooltip_position: Character {"top-left", "top-right", "bottom-left", "bottom-right"}: Hover tooltip corner.
title: Optional Character: Title (currently surfaced via the value label; reserved for future use).
theme: Optional Theme, list, or NA: Theme override. NULL enables light/dark auto-detection (matching draw()).
width: Optional Character or Numeric: Widget width.
height: Optional Character or Numeric: Widget height.
element_id: Optional Character: Explicit element ID.
filename: Optional Character: Static export of map widgets is not yet supported. Supplying a path raises an error.

Value

htmlwidget.

Details

The location column is matched to the geometry in the renderer, which accepts ISO-A3 / ISO-A2 / country code for countries, and FIPS / postal abbreviation / full name for US states (5-digit FIPS for counties). A join report in the corner surfaces any unmatched keys.

Examples

# Country choropleth from ISO-A3 codes
df <- data.frame(
  iso = c("USA", "CAN", "MEX", "BRA", "FRA"),
  gdp = c(25.5, 2.1, 1.4, 1.9, 2.9)
)
draw_choropleth(df, location = "iso", value = "gdp")


# US states by postal abbreviation, natural-breaks classification
states <- data.frame(
  st = state.abb,
  pop = as.numeric(state.x77[, "Population"])
)
draw_choropleth(
  states,
  location = "st",
  value = "pop",
  resolution = "state",
  classification = "jenks",
  colormap = "viridis"
)