Package {explodemap}

explodemap: Hierarchical Exploded-View Cartography

Description

Internal package declarations for NSE checks.

Author(s)

Maintainer: George Arthur prigasgenthian48@gmail.com

See Also

Useful links:

• https://prigasg.github.io/explodemap/

• https://github.com/PrigasG/explodemap

• Report bugs at https://github.com/PrigasG/explodemap/issues

Normalize input to an export-ready sf object in WGS84

Description

Normalize input to an export-ready sf object in WGS84

Usage

.as_export_sf(x)

Arguments

Value

sf object

Attach region labels to TIGER/Line data via county names

Description

Attach region labels to TIGER/Line data via county names

Usage

.attach_regions_tiger(sf_obj, fips, region_map, quiet = FALSE)

Build mapshaper CLI arguments

Description

Build mapshaper CLI arguments

Usage

.build_mapshaper_args(input, output, simplify = NULL)

Arguments

Value

Character vector of arguments for system2()

Download TIGER/Line county subdivision boundaries

Description

Download TIGER/Line county subdivision boundaries

Usage

.download_cousub(fips, crs)

Arguments

Value

sf object

Locate the mapshaper executable on the system path

Description

Locate the mapshaper executable on the system path

Usage

.find_mapshaper()

Value

Path to mapshaper executable

Generate initial radial anchors from the national centroid

Description

Generate initial radial anchors from the national centroid

Usage

.generate_anchors(
  block_df,
  nat_centroid,
  kappa = 1.8,
  padding = 50000,
  delta = 15000
)

Download national county name-to-FIPS lookup

Description

Download national county name-to-FIPS lookup

Usage

.get_national_counties()

Handle export logic

Description

Handle export logic

Usage

.handle_export(export, sf_exp_wgs, label)

Build plots for grouped layouts

Description

Build plots for grouped layouts

Usage

.make_grouped_plots(sf_orig, sf_local, sf_grouped, region_col, title, params)

Build standard original/exploded ggplot pair

Description

Build standard original/exploded ggplot pair

Usage

.make_plots(sf_orig, sf_exp, region_col, title, params)

Refine anchors with pairwise repulsion plus spring return

Description

Refine anchors with pairwise repulsion plus spring return

Usage

.refine_anchors(
  block_df,
  lambda = 0.18,
  eta = 0.18,
  padding_sep = 20000,
  max_iter = 60
)

Fast bulk GeoJSON via a single sf::st_write call

Description

Writes the whole sf to a temp GeoJSON file and passes the raw JSON string to the widget. The JS side does JSON.parse(), which avoids the fromJSON → R list → toJSON round-trip that can mangle deeply nested coordinate arrays.

Usage

.sf_to_geojson_fast(
  sf_obj,
  label_col,
  id_col = NULL,
  group_col = NULL,
  context_col = NULL,
  info_cols = NULL,
  info_title = label_col
)

Clear explodemap download cache

Description

Clear explodemap download cache

Usage

cache_clear(key = NULL)

Arguments

Value

Invisibly returns NULL. The function is called for its side effect of deleting cached .rds files and reporting what was removed.

List cached datasets

Description

List cached datasets

Usage

cache_list()

Value

Invisibly returns a character vector of cached .rds file names. The visible output is a message listing the cache directory and file sizes, or a message that the cache is empty.

Extract calibration row from an exploded_map

Description

Returns a one-row data.frame suitable for binding across datasets to build a calibration table.

Usage

calibration_row(x)

Arguments

Value

A one-row data.frame

Compute centroids without attribute warnings

Description

Wraps sf::st_centroid / sf::st_point_on_surface, operating on st_geometry() rather than the full sf object. Returns an sfc column.

Usage

centroid_geoms(x, centroid_fun = c("centroid", "point_on_surface"))

Arguments

Value

sfc geometry column of point centroids

Compute geometry statistics for parameter derivation

Description

Extracts w_bar, R_local, n_bar, n_regions, and the tightness ratio from a projected sf object with a grouping column.

Usage

compute_stats(
  sf_obj,
  region_col,
  centroid_fun = c("centroid", "point_on_surface")
)

Arguments

Value

A named list of geometry statistics

Derive displacement parameters from geometry statistics

Description

Implements Analytical Results 1 and 2 from the paper: alpha_r = gamma_r * w_bar / (2 * sin(pi / n_regions)) alpha_l = gamma_l * 2 * R_local / sqrt(n_bar)

Usage

derive_params(stats, gamma_r = 3, gamma_l = 1.136, p = 1.25)

Arguments

Value

Named list with alpha_r, alpha_l, p, gamma_r, gamma_l

Estimate block radius for each region

Description

Computes the 85th percentile of distances from child-unit centroids to their region centroid. The 85th percentile is preferred over the maximum because the maximum is sensitive to outlier units and produces over-conservative block radii.

Usage

estimate_block_radii(
  sf_obj,
  region_col,
  quantile_p = 0.85,
  centroid_fun = c("centroid", "point_on_surface")
)

Arguments

Value

data.frame with columns: region, block_radius, cx, cy, n_units

Create a three-level grouped exploded map

Description

Combines Level 1 (local explosion within regions) with Level 2/3 (anchor-based region block placement). This is the full three-level extension from Section 12 of the paper.

Usage

explode_grouped(
  sf_obj,
  region_col,
  mode = c("auto", "auto_collision", "manual"),
  anchors = NULL,
  alpha_l = NULL,
  p = 1.25,
  gamma_l = 1.136,
  kappa = 1.8,
  padding = 50000,
  delta = 15000,
  lambda = 0.18,
  eta = 0.18,
  padding_sep = 20000,
  anchor_expand = NULL,
  anchor_buffer = NULL,
  density_scale = NULL,
  block_sep = NULL,
  max_iter = 60,
  fix_invalid = TRUE,
  centroid_fun = c("centroid", "point_on_surface"),
  plot = TRUE,
  export = NULL,
  label = "Grouped Layout",
  quiet = FALSE
)

Arguments

Details

The guarantees of Propositions 1-3 apply strictly at Level 1. Higher levels preserve structural grouping and directional correspondence rather than topological coverage.

Value

A grouped_exploded_map S3 object (inherits from exploded_map)

Explode one selected section and keep the rest as context

Description

explode_section() is a dashboard-oriented helper for exploratory maps. It applies an exploded layout only to the requested section, then recombines the untouched remainder of the layer as geographic context. The result can be passed directly to focus_map() with context_col to fade or hide the non-selected features.

Usage

explode_section(
  sf_obj,
  section_col,
  section,
  region_col = section_col,
  layout = c("explode", "grouped"),
  context = c("fade", "hide", "none"),
  role_col = ".explodemap_role",
  all_values = "all",
  ...
)

Arguments

Value

An exploded_map or grouped_exploded_map object with recombined focus/context geometry and extra diagnostics.

Examples

poly <- function(xmin, ymin, xmax, ymax) {
  sf::st_polygon(list(rbind(
    c(xmin, ymin), c(xmax, ymin), c(xmax, ymax),
    c(xmin, ymax), c(xmin, ymin)
  )))
}

municipalities <- sf::st_sf(
  NAME = c("A", "B", "C", "D"),
  nj_region = c("South", "South", "North", "North"),
  county_name = c("Atlantic", "Cape May", "Bergen", "Hudson"),
  geometry = sf::st_sfc(
    poly(0, 0, 1000, 1000),
    poly(2000, 0, 3000, 1000),
    poly(0, 2000, 1000, 3000),
    poly(2000, 2000, 3000, 3000),
    crs = 3857
  )
)

focused <- explode_section(
  municipalities,
  section_col = "nj_region",
  section = "South",
  region_col = "county_name",
  alpha_r = 1800,
  alpha_l = 1200,
  plot = FALSE,
  quiet = TRUE
)

focus_map(
  focused,
  label_col = "NAME",
  context_col = ".explodemap_role",
  context_mode = "fade"
)

Explode any sf object with an existing grouping column

Description

Explode any sf object with an existing grouping column

Usage

explode_sf(
  sf_obj,
  region_col = "region",
  gamma_r = 3,
  gamma_l = 1.136,
  p = 1.25,
  alpha_r = NULL,
  alpha_l = NULL,
  refine = FALSE,
  refine_min_gap = NULL,
  refine_max_shift = NULL,
  refine_max_iter = 20,
  refine_step = 0.5,
  refine_within = c("region", "all"),
  allow_other = FALSE,
  fix_invalid = TRUE,
  centroid_fun = c("centroid", "point_on_surface"),
  plot = TRUE,
  export = NULL,
  label = "Custom Dataset",
  quiet = FALSE
)

Arguments

Value

An exploded_map S3 object

Core displacement algorithm (Algorithm 1 from the paper)

Description

Applies the hierarchical centroid-driven displacement field to every polygon. Each unit receives rigid-body translation t_i = alpha_r * dhat_state + alpha_l * s_i * dhat_local.

Usage

explode_sf_core(
  sf_obj,
  region_col,
  alpha_r,
  alpha_l,
  p = 1.25,
  centroid_fun = c("centroid", "point_on_surface")
)

Arguments

Details

Propositions 1-3 guarantee: exact geometry preservation, radial ordering, and bounded displacement (||t_i|| <= alpha_r + alpha_l).

Value

Exploded sf object (same CRS as input)

Explode any sf object using an external lookup table

Description

Joins the lookup to sf_obj before exploding. Unmatched units are labelled "Other".

Usage

explode_sf_with_lookup(
  sf_obj,
  join_col,
  lookup,
  lookup_key = join_col,
  region_col = "region",
  quiet = FALSE,
  ...
)

Arguments

Value

An exploded_map S3 object

Explode a US state from TIGER/Line data

Description

Downloads municipal boundaries automatically, groups by county-to-region mapping, derives parameters via Analytical Results 1-2, and returns an exploded_map S3 object.

Usage

explode_state(
  state_fips,
  crs,
  region_map,
  gamma_r = 3,
  gamma_l = 1.136,
  p = 1.25,
  alpha_r = NULL,
  alpha_l = NULL,
  refine = FALSE,
  refine_min_gap = NULL,
  refine_max_shift = NULL,
  refine_max_iter = 20,
  refine_step = 0.5,
  refine_within = c("region", "all"),
  allow_other = FALSE,
  fix_invalid = TRUE,
  centroid_fun = c("centroid", "point_on_surface"),
  plot = TRUE,
  export = NULL,
  label = paste0("FIPS ", state_fips),
  quiet = FALSE
)

Arguments

Value

An exploded_map S3 object

Export an exploded map as TopoJSON

Description

Converts an sf, exploded_map, or grouped_exploded_map object to TopoJSON using the external mapshaper command-line tool. The input is first written as a temporary GeoJSON file, then converted by mapshaper.

Usage

export_topojson(x, file, simplify = NULL, overwrite = FALSE)

Arguments

Details

This is intended as a convenience helper for downstream tools such as Power BI, D3.js, and Observable that prefer or require TopoJSON input.

This function requires the external mapshaper command-line tool to be installed and available on the system path. It can be installed with:

npm install -g mapshaper

The mapshaper tool is not an R package dependency; it is invoked via system2(). If mapshaper is not found, the function errors with an informative message.

Value

Invisibly returns the output file path.

Examples

## Not run: 
# Two-level export
result <- explode_sf(my_sf, region_col = "region", plot = FALSE)
export_topojson(result, "exploded.topojson")

# Three-level grouped export
grp <- explode_grouped(my_sf, region_col = "region", plot = FALSE)
export_topojson(grp, "grouped.topojson")

# With simplification (breaks Proposition 1 guarantee)
export_topojson(result, "simplified.topojson", simplify = 0.5)

# Raw sf object
export_topojson(my_sf, "raw.topojson", overwrite = TRUE)

## End(Not run)

Format a distance in metres as a human-readable km string

Description

Adapts precision to magnitude: "23.6 km" for large values, "0.067 km" for small ones, so tiny test geometries don't show "0 km".

Usage

fmt_dist(x_m)

Arguments

Value

Character string

Interactive focus-map viewer

Description

Renders spatial features as a smooth, interactive SVG map. Click any polygon to zoom in and lift it from the map with a "toast" effect; right-click or press Escape to reset. Camera transitions use D3's optimal zoom interpolation for fluid 60 fps motion with zero server round-trips.

Usage

focus_map(
  x,
  label_col = NULL,
  id_col = NULL,
  group_col = NULL,
  group_palette = NULL,
  context_col = NULL,
  context_values = "context",
  context_mode = c("fade", "hide", "show"),
  context_fill = "#cfd9df",
  context_opacity = 0.18,
  context_clickable = FALSE,
  focus_preset = c("none", "municipal", "drilldown", "municipal_drilldown"),
  simplify = TRUE,
  fill = "#2d6ea3",
  fill_opacity = 0.58,
  stroke = "#ffffff",
  lift_scale = 1.16,
  focus_padding = 40,
  focus_size = 0.76,
  min_focus_width = 0,
  min_focus_height = 0,
  tiny_feature_threshold = 48,
  tiny_feature_boost = 1,
  max_zoom = NULL,
  origin_context = c("none", "socket", "inset", "both"),
  origin_context_position = c("bottom-left", "bottom-right", "top-left", "top-right"),
  focus_context_opacity = 0.3,
  show_drag_zoom = FALSE,
  font_size = 14,
  show_labels = TRUE,
  show_sidebar = TRUE,
  performance_mode = NULL,
  info_cols = NULL,
  info_labels = NULL,
  info_title = NULL,
  info_position = c("top-right", "top-left", "bottom-right", "bottom-left"),
  info_card_scale = 1,
  area_min = 5000,
  width_min = 95,
  height_min = 28,
  width = "100%",
  height = "600px",
  elementId = NULL
)

focusmapOutput(outputId, width = "100%", height = "600px")

renderFocusmap(expr, env = parent.frame(), quoted = FALSE)

Arguments

Details

Accepts raw sf objects, exploded_map results from explode_sf, or grouped_exploded_map results from explode_grouped. For exploded objects, the displaced (WGS 84) geometry is used automatically.

Value

An htmlwidgets object.

Examples

poly <- function(xmin, ymin, xmax, ymax) {
  sf::st_polygon(list(rbind(
    c(xmin, ymin), c(xmax, ymin), c(xmax, ymax),
    c(xmin, ymax), c(xmin, ymin)
  )))
}

counties <- sf::st_sf(
  NAME = c("A", "B"),
  region = c("North", "South"),
  geometry = sf::st_sfc(
    poly(-74.2, 40.0, -74.0, 40.2),
    poly(-73.9, 40.0, -73.7, 40.2),
    crs = 4326
  )
)

focus_map(counties, label_col = "NAME", group_col = "region")

Focus-map option presets

Description

Returns a named list of focus_map() arguments for common interactive mapping workflows. Presets are intentionally plain lists so they can be inspected, modified, or passed through do.call().

Usage

focus_map_preset(
  name = c("municipal", "drilldown", "municipal_drilldown", "none")
)

Arguments

Value

A named list of focus_map() arguments.

Examples

focus_map_preset("municipal")

Compute region anchor positions for grouped layouts

Description

Implements the anchor layout procedure from Section 12. Supports three modes: automatic radial placement, automatic with collision resolution, and manual user-specified anchors.

Usage

layout_regions(
  sf_obj,
  region_col,
  mode = c("auto", "auto_collision", "manual"),
  anchors = NULL,
  kappa = 1.8,
  padding = 50000,
  delta = 15000,
  lambda = 0.18,
  eta = 0.18,
  padding_sep = 20000,
  max_iter = 60,
  quantile_p = 0.85,
  centroid_fun = c("centroid", "point_on_surface"),
  quiet = FALSE
)

Arguments

Value

data.frame with region, anchor_x, anchor_y, block_radius, n_units

Plot an exploded_map object

Description

Plot an exploded_map object

Usage

## S3 method for class 'exploded_map'
plot(x, which = c("exploded", "original", "both"), ...)

Arguments

Value

Invisibly returns x, the original exploded_map object. The method is called for its side effect of drawing the stored ggplot2 original and/or exploded map objects.

Plot a grouped_exploded_map object

Description

Plot a grouped_exploded_map object

Usage

## S3 method for class 'grouped_exploded_map'
plot(x, which = c("grouped", "original", "local", "all"), ...)

Arguments

Value

Invisibly returns x, the original grouped_exploded_map object. The method is called for its side effect of drawing the stored ggplot2 grouped, original, and/or local map objects.

Print an exploded_map object

Description

Print an exploded_map object

Usage

## S3 method for class 'exploded_map'
print(x, ...)

Arguments

Value

Invisibly returns x, the original exploded_map object. The method is called for its side effect of printing a compact diagnostic overview of units, regions, derived parameters, and optional refinement information.

Print a grouped_exploded_map object

Description

Print a grouped_exploded_map object

Usage

## S3 method for class 'grouped_exploded_map'
print(x, ...)

Arguments

Value

Invisibly returns x, the original grouped_exploded_map object. The method is called for its side effect of printing a compact diagnostic overview of units, regions, grouping mode, and grouped-layout parameters.

Summary of an exploded_map object

Description

Summary of an exploded_map object

Usage

## S3 method for class 'exploded_map'
summary(object, ...)

Arguments

Value

Invisibly returns object, the original exploded_map object. The method is called for its side effect of printing a human-readable summary of dataset size, geometry statistics, displacement parameters, refinement diagnostics, and implied calibration coefficients.

Summary of a grouped_exploded_map object

Description

Summary of a grouped_exploded_map object

Usage

## S3 method for class 'grouped_exploded_map'
summary(object, ...)

Arguments

Value

Invisibly returns object, the original grouped_exploded_map object. The method is called for its side effect of printing dataset size, grouping diagnostics, anchor parameters, and anchor radii.

Validate inputs before explosion

Description

Checks CRS, empty geometries, invalid geometries, region count, and unmatched "Other" units. Optionally repairs invalid geometries.

Usage

validate_input(sf_obj, region_col, allow_other = FALSE, fix_invalid = TRUE)

Arguments

Value

The (possibly repaired) sf object, invisibly