6  MapLibre: high-level API

library(rtemis.draw)

.:rtemis.draw 0.3.0 🖌 aarch64-apple-darwin23

Attaching package: 'rtemis.draw'

The following object is masked from 'package:graphics':

    Axis

Choropleth maps — regions shaded by a value — are rendered with MapLibre GL, a WebGL map renderer, rather than ECharts. As with the Sigma.js network renderer, rtemis.draw picks the most capable JavaScript library per plot type. The high-level draw_choropleth() and the low-level MapModel / MapLibreOption classes are the R counterparts of the choropleth renderer in rtemis.live.

Note on rendering There is no basemap: administrative boundaries are drawn on the themed page background, and the map auto-detects your system’s light/dark setting like every other draw_* function. The location-to-geometry join, the classification scale, and FIPS/ISO key normalization all run in the browser. A small report in the corner shows how many rows matched the geometry — and surfaces any keys that did not, so a silent join failure is always visible.

6.1 Countries

The simplest input is a data frame with a location column and a value column. For world maps the location key is an ISO-A3 (or ISO-A2) country code; resolution = "country" is the default.

countries <- data.frame(
  iso = c(
    "USA", "CAN", "MEX", "BRA", "ARG", "GBR", "FRA", "DEU", "ESP", "ITA",
    "NOR", "SWE", "POL", "RUS", "CHN", "JPN", "KOR", "IND", "IDN", "AUS",
    "NZL", "ZAF", "EGY", "NGA", "KEN", "SAU", "TUR", "IRN", "CHL", "COL"
  ),
  life_exp = c(
    78.5, 82.3, 75.0, 75.9, 76.7, 81.3, 82.5, 81.0, 83.5, 82.9,
    82.8, 82.8, 78.3, 73.2, 78.2, 84.6, 83.4, 70.2, 71.7, 83.4,
    82.1, 64.9, 71.8, 55.7, 66.7, 75.1, 77.7, 76.7, 80.2, 77.3
  )
)

draw_choropleth(
  countries,
  location = "iso",
  value = "life_exp",
  value_label = "Life expectancy"
)

The renderer accepts ISO-A3, ISO-A2, or upper/lower case, so a column of two-letter codes joins just as well.

6.2 US states

Set resolution = "state" to join to US states. The location key can be a FIPS code, a postal abbreviation, or a full state name — all normalize to the same 2-digit FIPS id. Here we use the built-in state.x77 data:

states <- data.frame(
  abbr = state.abb,
  income = as.numeric(state.x77[, "Income"])
)

draw_choropleth(
  states,
  location = "abbr",
  value = "income",
  resolution = "state",
  value_label = "Income (1974, $)",
  color_scheme = "greens"
)

6.3 Classification and color schemes

classification controls how values are binned into color classes: "quantile" (equal counts, the default), "equal" (equal-width intervals), or "jenks" (natural breaks). num_classes sets the number of classes (2–12), and color_scheme selects the ramp.

draw_choropleth(
  states,
  location = "abbr",
  value = "income",
  resolution = "state",
  value_label = "Income",
  classification = "jenks",
  num_classes = 6,
  color_scheme = "viridis"
)

Sequential schemes — "blues", "viridis", "ylorrd", "greens", "magma" — suit data with a natural low-to-high order. Diverging schemes — "rdbu", "rdylgn", "spectral", "brbg" — emphasize departure from a midpoint:

state_pop <- data.frame(
  abbr = state.abb,
  illiteracy = as.numeric(state.x77[, "Illiteracy"])
)

draw_choropleth(
  state_pop,
  location = "abbr",
  value = "illiteracy",
  resolution = "state",
  value_label = "Illiteracy (%)",
  color_scheme = "rdylgn",
  classification = "equal"
)

6.4 Tooltips and styling

Pass tooltip with extra column names to surface them on hover. The remaining arguments tune appearance: opacity, show_boundaries, outline_width, and the corner anchors legend_position / tooltip_position.

states_full <- data.frame(
  abbr = state.abb,
  name = state.name,
  income = as.numeric(state.x77[, "Income"]),
  murder = as.numeric(state.x77[, "Murder"])
)

draw_choropleth(
  states_full,
  location = "abbr",
  value = "income",
  resolution = "state",
  value_label = "Income",
  tooltip = c("name", "murder"),
  color_scheme = "blues",
  outline_width = 0.5,
  legend_position = "bottom-left",
  tooltip_position = "top-right"
)

Counties are supported too (resolution = "county", joining on 5-digit FIPS).

6.5 Lower-level API

draw_choropleth() builds a MapModel and a MapLibreOption render spec internally. To assemble rows by hand or set the render spec directly and draw it with draw(), see the MapLibre low-level S7 API chapter.