Add map composition helpers for tmap, mapgl, leaflet, and QGIS

[NewGraphEnvironment]

Problem

gq handles style translation (colors, weights, classification) but map composition — scales, logos, north arrows, element placement, basemaps, bbox padding — is copy-pasted between projects. Every bookdown report and vignette across the org re-implements the same layout boilerplate. The cartography conventions in soul describe what to do (four-corner rule, map-fills-frame, suppress auto-legends) but there's no code encoding those defaults.

Proposed Solution

Extend gq with composition helpers that encode our cartographic conventions as sensible defaults with overrides. Three interactive targets reflect actual usage: mapgl (default per conventions), leaflet (Shiny apps, mapgl workarounds), and QGIS (field work, Mergin Maps).

Static (tmap v4)

Function	Purpose
gq_tmap_layout()	Standard margins, font, frame settings
gq_tmap_legend()	Position, sizing, background — follows four-corner rule
gq_tmap_scalebar()	Position, auto-breaks appropriate for extent
gq_tmap_logo()	NGE logo placement, corner selection
gq_tmap_basemap()	maptiles provider + alpha blending for terrain context
gq_tmap_keymap()	Inset overview/context map

Interactive — mapgl (default)

Function	Purpose
gq_mapgl_basemap()	Standard tile source configuration
gq_mapgl_controls()	Navigation, scale bar, layer toggle
gq_mapgl_popup()	Standard popup template from column names

Interactive — leaflet

mapgl is the default per conventions, but leaflet keeps being needed — diggs Shiny app, restoration watershed picker, and whenever mapgl hits limitations. Worth having helpers rather than re-inventing each time.

Function	Purpose
gq_leaflet_basemap()	Standard tile layers with provider defaults
gq_leaflet_controls()	Layer toggle, scale bar
gq_leaflet_popup()	Standard popup from column names

Track which mapgl limitations force the leaflet fallback — file upstream issues or document workarounds.

QGIS

gq already extracts styles from QGIS (gq_qgs_extract). The reverse — pushing registry styles into QGIS projects or QML files — would close the loop for field work and Mergin Maps. This is heavier (Python/XML generation) so may belong in a later phase, but noting it here since QGIS is a core part of the workflow.

Design principles

• Defaults encode soul cartography conventions (four-corner rule, element spacing, no titles, suppress auto-legends)
• All defaults overridable — conventions are defaults not constraints
• Ship NGE logo as inst/assets/logo.png

Out of scope (stays in soul)

• Conventions prose (design rationale, self-review checklist)
• Style registry unchanged — composition sits alongside

Relates to NewGraphEnvironment/sred-2025-2026#5

[NewGraphEnvironment]

Learnings from fresh subbasin vignette (map composition proof-of-concept)

Built a full tmap v4 map in fresh that exercises most of the composition patterns gq#14 would encapsulate. Capturing everything here so it can feed the implementation.

Working patterns (ready to wrap as gq helpers)

gq_tmap_style() integration — do.call(tm_polygons, gq_tmap_style(reg$layers$lake)) works cleanly for single-style layers. Same for wetlands, streams.

Classified layers — gq_tmap_classes() values plug into tm_scale_categorical():

cls <- gq_tmap_classes(reg$layers$streams_salmon)
tm_lines(col = "mapping_code",
  col.scale = tm_scale_categorical(values = cls$values, labels = cls$labels))

Manual legends (v4 syntax) — v3→v4 migration:

• type = "lines" not "line"
• type = "polygons" not "fill"
• fill not col for fill color in lines/polygons
• type = "symbols" works as-is

Logo — tm_logo(system.file("logo", "nge_icon_200.png", package = "gq"), position = c("right", "top"), height = 3) works perfectly.

Keymap inset — grid::viewport() after print(m):

print(m)
print(keymap, vp = grid::viewport(x = 0.895, y = 0.115, width = 0.19, height = 0.21))

Tricky to get right — viewport coords are device-relative (0-1), not frame-relative. Clipping happens if edges exceed device bounds. This is the strongest case for a gq_tmap_keymap() helper that computes viewport from a corner spec.

Layout lessons

Tight margins — inner.margins = c(0.005, 0.005, 0.005, 0.005), outer.margins = 0. Anything more creates dead bands.

Bbox must match page aspect ratio — AOI at 0.9:1 on an 8.5x9.5 figure works. On 8x10 it creates top/bottom whitespace bands. A helper could compute optimal figure dimensions from the AOI extent:

gq_tmap_figsize(aoi, max_width = 8.5, max_height = 11)
# Returns list(width = 8.5, height = 9.5)

Legend placement — top-left overlapped the AOI in this subbasin. Moved to bottom-left where natural whitespace existed. A helper could auto-detect the best corner by checking which has least AOI coverage.

Layer draw order matters — lakes should render ON TOP of stream layers so the lake fill covers stream lines that pass through. Current order has streams over lakes which looks messy.

Hillshade/basemap needed — the map lacks terrain context. gq_tmap_basemap() from the issue spec would solve this. maptiles package with alpha blending.

Gaps discovered (new issues filed)

• gq#15 — Missing highway/arterial codes in roads_dra classification (RH1, RH2, RA1, RA2, RC1, RC2)
• gq#16 — Symbol size translation: registry mark radius doesn't map to tmap size units. Falls at size = 0.15 were invisible, needed size = 0.5.
• gq#7 (existing) — Label translation: lake labels exist in registry JSON but no gq_tmap_labels() to extract them

Data caching for vignette iteration

Neither drift nor flooded use persistent caching. For fast map iteration, saveRDS()/readRDS() of query results to a temp file cut render time from ~60s to ~3s. Could become a convention for vignettes that query databases:

cache_path <- file.path(tempdir(), "vignette_cache.rds")
if (file.exists(cache_path)) {
  d <- readRDS(cache_path)
} else {
  d <- list(streams = frs_network(...), ...)
  saveRDS(d, cache_path)
}

What belongs in gq vs fresh

The fresh vignette should demonstrate frs_network() — the data query. All the map composition boilerplate (layout, legend, keymap, basemap, symbol sizing, bbox calculation) should live in gq as helpers per this issue. The fresh vignette would then simplify to:

result <- frs_network(blk, drm, tables = list(...))
gq_tmap_map(result, aoi = aoi, style = "salmon_habitat")  # one-liner

[NewGraphEnvironment]

tmap v4 layout learnings from fresh subbasin vignette (PR NewGraphEnvironment/fresh#13)

The core problem: element-to-frame distance

tmap v4 has no direct control over element-to-frame distance. There are three margin layers but none of them pin an element N pixels from the frame:

Param	What it controls
outer.margins	Device edge → frame
inner.margins	Frame → geographic content
Element margins	Spacing between stacked elements (legend + scalebar), NOT from frame
Element position	Coarse grid ("left"/"center"/"right", "top"/"bottom") with tmap's own padding baked in

A gq_tmap_layout() helper should abstract this — the user says "tight" or "standard" and gets the right combination.

Aspect ratio matching eliminates dead bands

The biggest single fix for white space was matching the PNG device dimensions to the bbox aspect ratio:

bb <- st_bbox(aoi)
asp <- (bb["xmax"] - bb["xmin"]) / (bb["ymax"] - bb["ymin"])
# For 8.5in wide: height = 8.5 / asp

When device aspect ≠ bbox aspect, tmap letterboxes. With asp = 0 tmap stretches to fill but still adds internal padding. Matching dimensions eliminates this entirely. A helper should compute this automatically.

Bbox expansion for vertical fill

Even with matched aspect ratios, adding slight bbox padding helps the map "breathe":

y_pad <- (bb["ymax"] - bb["ymin"]) * 0.03
bb["ymin"] <- bb["ymin"] - y_pad
bb["ymax"] <- bb["ymax"] + y_pad
bb_box <- st_as_sfc(bb, crs = st_crs(aoi))
m <- tm_shape(bb_box) + tm_borders(lwd = 0, col = NA) + ...

The invisible bbox shape forces tmap to use the expanded extent as its viewport.

Keymap inset: raw grid, not tmap

The keymap is a grid::viewport overlay — completely outside tmap's coordinate system. This means:

• It CAN overlap the frame (it's drawn after tmap finishes)
• Coordinates are device-relative (0-1), not frame-relative
• Must manually calculate: x ± width/2 stays inside frame bounds

The math for "inside frame, bottom-right corner":

# With outer.margins = 0.003, frame is at ~0.003 from device edge
# width=0.25, half=0.125 → x=0.86 puts right edge at 0.985
# height=0.22, half=0.11 → y=0.12 puts bottom edge at 0.01
grid::viewport(x = 0.86, y = 0.12, width = 0.25, height = 0.22)

A helper should take corner = "bottom-right" and size = "medium" and compute this.

Scale bar breaks

tm_scalebar(breaks = c(0, 1, 2, 3)) gives clean 3-segment 1km breaks. But it gets squeezed when inner.margins is too tight at the bottom. Need at least inner.margins[1] >= 0.04 (bottom) for the scale bar text to render. The breaks param is in map units (km for projected CRS), not raw CRS units.

Layer draw order matters

Lakes must render AFTER streams so lake fill cleanly covers stream lines:

wetlands → streams → lakes → lake labels → transport → habitat → points

Legend suppression

tmap v4's tm_legend(labels = ...) does NOT suppress unwanted levels. To remove "Access" from a 3-level categorical, you must:

1. Set Access to NA in the factor
2. Split into separate sf objects (access as plain lines, habitat as classified)
3. Plot access segments with tm_lines(col = "#a9e0ff") (stream color)
4. Plot habitat segments with tm_scale_categorical() on only the 2 remaining levels

Working layout params that produced a tight, frame-filling map

tm_layout(
  frame = TRUE,
  frame.lwd = 0.5,
  asp = 0,
  legend.position = c("left", "bottom"),
  inner.margins = c(0.04, 0.001, 0.001, 0.001),  # bottom needs room for scalebar
  outer.margins = c(0.003, 0.003, 0.003, 0.003),
  meta.margins = 0
)
tm_scalebar(breaks = c(0, 1, 2, 3), text.size = 0.5,
            position = c("center", "bottom"), margins = c(0, 0, 0, 0))
tm_logo(logo_path, position = c("right", "top"), height = 2.5,
        margins = c(0, 0, 0, 0))

What gq_tmap_layout() should do

1. Accept AOI bbox + page dimensions → compute device aspect ratio
2. Set frame/outer/inner margins for "tight" vs "standard" profiles
3. Position scalebar, logo, legend in separate corners with consistent spacing
4. Return keymap viewport coords for a given corner and size
5. Handle the bbox expansion trick automatically