dragmapr
Drag map regions into any layout · export offsets · render a static image
🗺️
1 · Setup
pak::pak("PrigasG/dragmapr")
Install from GitHub (CRAN release coming).
library(dragmapr)

prepare_dragmapr_sf(x)
Converts lon/lat data to a projected CRS (EPSG:3857 by default), repairs invalid geometry, and keeps only polygon features. Run this first if your data uses degrees.
prepare_dragmapr_sf(my_sf) prepare_dragmapr_sf(my_sf, target_crs = 32632)
Core Workflow
① Prepareprepare_dragmapr_sf()
→
② Dragdrag_map_prototype()
→
③ Downloadoffset CSVs from browser
→
④ Renderstatic image
💡 Using Spatial Studio? Skip ③–④ and call `render_dragmapr_project("project.zip")` instead.
Read & Apply Offsets
read_offsets(file)
Load a region offset CSV downloaded from the browser.
apply_offsets(x, offsets)
Shift an `sf` object's geometry by the saved region offsets.
read_label_state(file)
Load a label offset CSV.
apply_label_state(labels, file)
Apply saved label positions to a label table.
# Typical round-trip reg <- read_offsets("drag_region_offsets.csv") labs <- read_label_state("drag_label_offsets.csv") render_dragged_map(my_sf, region_col = "region", region_offsets = reg, label_offsets = labs)
2 · Open the Interactive Map
drag_map_prototype(x, region_col, …)
Writes a self-contained HTML file and (optionally) opens it in your browser. Drag regions and labels, then download the two offset CSVs from the side panel.

Argument | What it does
--- | ---
x | Your projected `sf` object
region_col | Column that groups regions (required)
label_col | Column to use as label text (default = region_col)
labels | `TRUE` auto-labels · `FALSE` no labels · data frame for custom
open | `TRUE` opens browser immediately
show_legend | `TRUE` adds a region colour legend
map_background | "white" · "light_grid" · "dark" · "transparent"
region_palette | Named vector of hex colours per region
file | Where to save the HTML (temp file if NULL)
side_panel | `FALSE` hides panel (use in Shiny apps)
transition | Bloom config for parent/child groupings adv

# Minimal — opens browser drag_map_prototype(my_sf, region_col = "region", open = TRUE) # With legend and dark background drag_map_prototype(my_sf, "region", show_legend = TRUE, map_background = "dark", open = TRUE)
RStudio Addin
dragmapr_addin()
Or use Addins › Launch dragmapr in the RStudio toolbar. Point-and-click column selection, drag the map, click Done — saves `region_offsets` and `label_offsets` to `.GlobalEnv`.
# Load your sf first, then launch regions <- prepare_dragmapr_sf(sf::st_read("map.shp")) dragmapr_addin() # After clicking Done: render_dragged_map(regions, region_col = "name", region_offsets = region_offsets, label_offsets = label_offsets, file = "map.png")
3 · Labels
make_region_labels(x, region_col, label_col)
Derive one label per region from your data — the easiest starting point.
as_drag_labels(df)
Validate and wrap a custom label data frame. Needs columns: `label_id`, `region`, `label`, `x`, `y`.
as_drag_annotations(df, connector, connector_type)
Turns label rows into draggable callout boxes with optional connector lines. Types: `"straight"` · `"elbow"` · `"curve"` · `"squiggle"`.
select_label_ids(labels, ids)
Show only the listed label IDs (e.g. for Shiny filter controls).
# Auto labels lbs <- make_region_labels(my_sf, region_col = "region") # Custom callout box with a curved connector note <- as_drag_annotations( data.frame(label_id="n1", region="North", label="Key area", x=5e4, y=1.5e5), connector=TRUE, connector_type="curve")
🔁 Save and restore label positions across sessions with `read_label_state()` / `apply_label_state()`.
Built-in Examples
`basic_draggable_map.R` — four regions, zero setup
`shiny_draggable_export.R` — live preview + PNG export
`shiny_spatial_studio.R` — full Spatial Studio app
`branch-bloom-tester.R` — parent/child bloom demo
`explodemap_hhs_labels.R` — HHS-style exploded layout
source(system.file( "examples", "basic_draggable_map.R", package = "dragmapr"))
dragmapr
Static export · Spatial Studio · Hierarchy / Bloom · Utilities
🗺️
4 · Static Export
render_dragged_map(x, region_col, …)
Applies saved offsets and renders a `ggplot2` image. Returns the ggplot object; saves to disk when `file` is set.

Argument | What it does
--- | ---
region_offsets | Data frame or CSV path from browser download
label_offsets | Label CSV or data frame
labels | Label table · `FALSE` to skip labels
show_legend | Show region fill legend
legend_title | Legend heading text
map_background | "white" · "light_grid" · "dark"
connector_endpoint | "none" or "arrow" on label connectors
show_origin_outlines | Ghost outlines of original positions
show_movement_connectors | Lines from original → dragged position
file | Output path (.png / .pdf / .svg)
width, height, dpi | Output dimensions (inches & resolution)

render_dragged_map(my_sf, region_col = "region", region_offsets = "drag_region_offsets.csv", label_offsets = "drag_label_offsets.csv", show_legend = TRUE, file = "map.png", width=10, height=8, dpi=300)

render_dragmapr_project(zip, …)
Reads a Spatial Studio project ZIP and renders the final image in one call. No separate CSVs needed.
render_dragmapr_project("project.zip", file="map.png", width=10, height=8)
read_dragmapr_project(zip)
Inspect a saved project bundle: source geometry, offsets, labels, palette, and metadata.
write_dragmapr_project(x, …, file)
Bundle source geometry + offsets + metadata into a ZIP for sharing.
Spatial Studio & Shiny
shiny_spatial_studio.R example
Full-featured Shiny app: upload shapefiles/GeoJSON/GPKG, pick grouping and label columns, drag the map, switch columns while keeping layout, export PNG/PDF/ZIP.
source(system.file("examples", "shiny_spatial_studio.R", package="dragmapr"))

read_dragmapr_sf_upload(input$file)
Read a user-uploaded spatial file (ZIP shapefile, GeoJSON, GPKG) inside a Shiny server function.
read_dragmapr_sf_url(url)
Download and read a spatial file from a URL.
dragmapr_iframe_bridge()
JavaScript bridge that relays drag state from the helper `<iframe>` to Shiny input values. Add to your UI once.
# Minimal Shiny integration ui <- fluidPage( dragmapr_iframe_bridge(), uiOutput("map_iframe")) server <- function(input, output, session) { sf_data <- reactive({ read_dragmapr_sf_upload(input$file) }) }

suggest_offsets(x, region_col, method)
Generate automatic starting offsets — useful as a Spatial Studio default before any dragging. Methods: `"radial"` · `"grid"` · `"directional"`.
Hierarchy & Bloom advanced
Parent/child bloom lets you drill into sub-regions with a leaf-flip animation while keeping the rest of the map at parent level.
detect_hierarchy_columns(x)
Scan all columns and return candidate parent/child pairs based on nesting structure.
recommend_dragmapr_hierarchy(x)
Recommend the best grouping column and its child column, with a data-driven reason.
validate_bloom_hierarchy(x, parent_col, child_col)
Check that the child column genuinely nests inside the parent — required before arming a bloom transition.
make_hierarchy_key(x, cols)
Build stable composite keys when child names repeat across parents.
build_branch_transition_data(x, parent_col, child_col)
Build the `transition` list to pass to `drag_map_prototype()`, including dissolved parent shells and bloom group mappings.
make_branch_bloom_labels(x, …)
Build a combined label table covering both parent and child levels for a bloom helper.
inherit_layout(offsets, x, from_col, to_col)
Carry drag offsets from one grouping column to another (e.g. parent → child positions on first visit).
transition_options() / build_elastic_transition()
Create static transition frames and dotted group boundaries for package-level transition testing.
make_group_boundaries(x, group_col)
Return the padded dotted boundary geometry used as a group-drag frame.
# Typical bloom setup td <- build_branch_transition_data( my_sf, parent_col="region", child_col="state") drag_map_prototype(td$data, "region", transition=td$transition, open=TRUE)

Utilities & Diagnostics
dragmapr_diagnostics(x)
Report CRS, geometry type, column types, and potential issues before you start dragging.
profile_spatial_upload(x)
Summarise an uploaded file: row count, CRS, hierarchy candidates, recommended grouping.
summarise_spatial_crs(x)
Human-readable description of the CRS and whether reprojection is needed.
create_layout_snapshot() / restore_layout_snapshot()
Capture and restore offsets for a grouping while switching columns or sessions.
layout_metrics(before, after, id_col)
Measure drift and stability between two map layouts.
example_hhs_layout() / example_panel_layout()
Return small built-in layouts for testing and examples — no external data needed.
💡 Aliases `make_labels()`, `read_label_offsets()`, and `apply_label_offsets()` are kept for older scripts but emit deprecation warnings.