The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Getting started with dragmapr

dragmapr is built around a deliberately small loop for draggable plots:

  1. Start with projected sf geometry and a grouping column.
  2. Open the draggable browser helper with drag_map_prototype(open = interactive()).
  3. Drag regions, labels, or annotation boxes until the layout looks right.
  4. Copy or download the offset CSVs from the helper panel.
  5. Optionally reproduce the layout as a static ggplot2 image with render_dragged_map().

The interactive helper is the primary deliverable. Step 5 is optional — use it when you need a reproducible image for a report or publication.

Toy geometry

All examples below use a projected toy dataset so the workflow can be tested without downloading shapefiles.

library(dragmapr)

make_square <- function(x0, y0, size = 100000) {
  sf::st_polygon(list(rbind(
    c(x0, y0), c(x0 + size, y0), c(x0 + size, y0 + size),
    c(x0, y0 + size), c(x0, y0)
  )))
}

regions <- sf::st_sf(
  region = c("North", "South", "East", "West"),
  label  = c("North", "South", "East", "West"),
  geometry = sf::st_sfc(
    make_square(0,       140000),
    make_square(0,            0),
    make_square( 140000,  70000),
    make_square(-140000,  70000),
    crs = 3857
  )
)

drag_map_prototype() — full parameter reference

Data

These three arguments identify the geometry and what to group or label.

Argument Default Description
x (required) Projected sf object. Must not be in a geographic (lon/lat) CRS.
region_col (required) Column name that defines draggable groups.
label_col region_col Column used for label text. Defaults to the grouping column. 
# Minimal call — one grouping column used for both groups and labels
drag_map_prototype(regions, region_col = "region", open = interactive())

# Separate column for label text
drag_map_prototype(regions, region_col = "region", label_col = "label", open = interactive())

Labels

Control whether labels appear and whether they can be dragged independently.

Argument Default Description
labels TRUE TRUE derives one label per region automatically. FALSE shows no labels. Supply a data frame from as_drag_labels() or as_drag_annotations() for custom labels.
draggable_labels TRUE When TRUE, labels can be moved independently. When FALSE, labels follow their region but cannot be repositioned on their own. 
# No labels
drag_map_prototype(regions, region_col = "region", labels = FALSE, open = interactive())

# Labels follow regions but cannot be dragged separately
drag_map_prototype(regions, region_col = "region",
                   draggable_labels = FALSE, open = interactive())

# Custom label data frame
custom_labels <- make_region_labels(regions, region_col = "region", label_col = "label")
drag_map_prototype(regions, region_col = "region",
                   labels = custom_labels, open = interactive())

Label styling

Choose between three marker shapes for short text labels — rounded box, circle, or text-only — and control their sizes and font.

Argument Default Description
label_marker TRUE Draw a visible marker shape behind label text. FALSE is a shortcut for label_marker_shape = "none".
label_marker_shape "rect" Shape behind the label text: "rect" (rounded box), "circle", or "none" (text only with an invisible drag target).
label_text_size 11 Label text size in browser pixels. Applies to all label types.
label_width 64 Width of rounded-box label markers in pixels.
label_height 30 Height of rounded-box label markers in pixels.
label_radius 12 Circle radius in pixels. Used when label_marker_shape = "circle".
label_box_width 150 Width of draggable annotation box (info-box style) in pixels.
label_box_height 72 Height of draggable annotation box in pixels. 
# Rounded-box markers (default) — adjust size and text
drag_map_prototype(
  regions, region_col = "region",
  label_marker_shape = "rect",
  label_text_size    = 12,
  label_width        = 80,
  label_height       = 32,
  open = interactive()
)

# Circle markers
drag_map_prototype(
  regions, region_col = "region",
  label_marker_shape = "circle",
  label_radius       = 18,
  label_text_size    = 11,
  open = interactive()
)

# Text only — no visible marker, just draggable text
drag_map_prototype(
  regions, region_col = "region",
  label_marker_shape = "none",
  label_text_size    = 13,
  open = interactive()
)

# Annotation boxes (info-box style with connectors)
notes <- as_drag_annotations(
  make_region_labels(regions, region_col = "region"),
  width_px       = 160,
  height_px      = 70,
  connector      = TRUE,
  connector_type = "elbow"
)
drag_map_prototype(
  regions, region_col = "region",
  labels           = notes,
  label_box_width  = 160,
  label_box_height = 70,
  open = interactive()
)

Connectors

Connector lines link a label or annotation box back to its region anchor. They are only drawn for labels that have connector = TRUE in their label data frame — set that flag via as_drag_annotations(..., connector = TRUE) or as_drag_labels(). The line style ("straight", "elbow", "curve", "squiggle") is stored per-label in the connector_type column.

Argument Default Description
connector_color "#334155" Browser connector line colour.
connector_linewidth 1.3 Connector line thickness in browser pixels.
connector_linetype "solid" Browser connector line pattern: "solid", "dashed", or "dotted".
connector_endpoint "none" Browser connector endpoint: "none" or "arrow".
connector_smart FALSE Let the browser choose straight, elbow, or curved connector geometry from the current label displacement. 
drag_map_prototype(
  regions, region_col = "region",
  labels              = notes,   # labels with connector = TRUE
  connector_color     = "#334155",
  connector_linewidth = 2,
  connector_linetype  = "dashed",
  connector_endpoint  = "arrow",
  connector_smart     = TRUE,
  open = interactive()
)

Movement context

Movement context is optional and off by default. It helps explain where a moved region came from without changing the underlying offset data.

Argument Default Description
show_origin_outlines FALSE Draw the original outline for regions with non-zero offsets.
show_movement_connectors FALSE Draw a line from each moved region’s original representative point to its current location.
movement_connector_color "#64748b" Movement connector colour.
movement_connector_opacity 0.72 Movement connector opacity from 0 to 1.
movement_connector_linewidth 1.4 Browser movement connector thickness in pixels.
movement_connector_linetype "solid" Movement connector pattern: "solid", "dashed", or "dotted".
movement_connector_endpoint "closed" Movement connector endpoint: "closed", "open", or "none".
show_drag_trail FALSE Browser-only fading outline trail while a region is actively dragged. 
drag_map_prototype(
  regions, region_col = "region",
  show_origin_outlines = TRUE,
  show_movement_connectors = TRUE,
  movement_connector_color = "#64748b",
  movement_connector_linetype = "dashed",
  movement_connector_endpoint = "open",
  show_drag_trail = TRUE,
  open = interactive()
)

Static exports support origin outlines and movement connectors too:

render_dragged_map(
  regions,
  region_offsets = region_offsets,
  region_col = "region",
  show_origin_outlines = TRUE,
  show_movement_connectors = TRUE,
  movement_connector_linetype = "dotted",
  movement_connector_endpoint = "closed"
)

Initial positions

Supply previously exported offset tables to pre-load a saved layout so dragging can continue from where it left off.

Argument Default Description
region_offsets NULL Data frame with columns region, dx_m, dy_m. All regions start at zero when NULL.
label_offsets NULL Data frame with columns label_id, region, dx_m, dy_m. All labels start at zero when NULL. 
# Resume from previously downloaded CSVs
region_csv <- read_offsets("drag_region_offsets.csv")
label_csv  <- read_label_state("drag_label_offsets.csv")

drag_map_prototype(
  regions, region_col = "region",
  region_offsets = region_csv,
  label_offsets  = label_csv,
  open = interactive()
)

read_label_offsets() is retained as an alias for read_label_state(), and apply_label_offsets() is retained as an alias for apply_label_state(). Likewise, make_labels() remains an alias for make_region_labels() for older scripts.

If the offsets were exported as a Spatial Studio project ZIP, use the one-line project renderer instead of wiring the CSV files together manually:

render_dragmapr_project(
  "dragmapr-project.zip",
  file = "dragged-map.png"
)

RStudio addin

In RStudio, install the package and use Addins > Launch dragmapr to open a compact prototype gadget. The addin looks for sf objects in .GlobalEnv, lets you choose the region and label columns, and assigns region_offsets and label_offsets when you click Done. Create or load the sf object before opening the addin. If you call dragmapr_addin() directly, pass env = to work with another environment.

Colour palette

Argument Default Description
region_palette NULL Named character vector mapping each region value to a hex colour string. Uses a built-in 8-colour cycling palette when NULL.

Matching the interactive palette to a render_dragged_map() call makes the draggable preview and the final static image look identical.

my_palette <- c(
  North = "#4C78A8",
  South = "#F58518",
  East  = "#54A24B",
  West  = "#B279A2"
)

drag_map_prototype(
  regions, region_col = "region",
  region_palette = my_palette,
  show_legend    = TRUE,
  open = interactive()
)

Legend

A compact colour legend can be embedded directly inside the browser helper. It is hidden by default because many maps are labelled and need no legend.

Argument Default Description
show_legend FALSE Show a colour legend in the helper.
max_legend_keys 25 Suppress the legend automatically when the number of groups exceeds this value. Set to Inf to always show it regardless of group count.
legend_position "bottom" Where the legend appears: "bottom", "top", "left", "right", or "none".
legend_title "Region" Title shown above the legend keys.
legend_values NULL Optional character vector of region values to include in the legend. NULL includes all values. 
drag_map_prototype(
  regions, region_col = "region",
  region_palette  = my_palette,
  show_legend     = TRUE,
  legend_position = "bottom",   # "top" | "left" | "right" | "none"
  legend_title    = "Region",
  legend_values   = c("North", "East"),
  max_legend_keys = 25,
  open = interactive()
)

Use label_values when an app should temporarily display only selected labels while preserving all label offsets:

drag_map_prototype(
  regions, region_col = "region",
  label_values = c("North", "East"),
  open = interactive()
)

Output file and display

Argument Default Description
file "drag-map.html" File path for the written standalone HTML.
open FALSE Open the file in the default browser via browseURL() after writing.
side_panel TRUE Show the built-in copy/download side panel. Shiny apps that provide their own export controls can set this to FALSE to reclaim the full canvas.
map_background "white" Helper background: "white", "transparent", "light_grid", or "dark". 
# Write to a chosen path without opening (e.g. CI, server, or Shiny)
drag_map_prototype(
  regions, region_col = "region",
  file       = "output/my_map.html",
  map_background = "light_grid",
  side_panel = TRUE,
  open       = FALSE
)

# Embedded in a Shiny app — hide the panel; the app provides its own controls
drag_map_prototype(
  regions, region_col = "region",
  side_panel = FALSE,
  file       = tempfile(fileext = ".html")
)

Optional: Static rendering

When you need a reproducible ggplot2 image, pass the exported offset tables to render_dragged_map(). The data frames below stand in for downloaded CSVs:

region_offsets <- data.frame(
  region = c("North", "South", "East", "West"),
  dx_m   = c(0, 0,  60000, -60000),
  dy_m   = c(50000, -50000, 0, 0)
)

label_state <- data.frame(
  label_id = c("North", "South", "East", "West"),
  region   = c("North", "South", "East", "West"),
  dx_m     = c(0, 0,  25000, -25000),
  dy_m     = c(30000, -30000, 0, 0)
)

render_dragged_map(
  regions,
  region_offsets = region_offsets,
  region_col     = "region",
  label_col      = "label",
  label_offsets  = label_state,
  title          = "Synthetic draggable map"
)

The same annotation types available in the interactive helper work in static output:

notes <- as_drag_annotations(data.frame(
  label_id = "east-note",
  region   = "East",
  label    = "The East label can become a longer draggable note.",
  x = 210000, y = 120000
), connector = TRUE, connector_type = "squiggle")

render_dragged_map(
  regions,
  region_offsets      = region_offsets,
  region_col          = "region",
  labels              = notes,
  label_offsets       = data.frame(
    label_id = "east-note", region = "East",
    dx_m = 80000, dy_m = 45000
  ),
  connector_linewidth = 0.8,
  connector_linetype  = "dotted",
  connector_endpoint  = "arrow",
  legend_title        = "Region",
  map_background      = "light_grid",
  title               = "Static output with an annotation box"
)

Running examples

Installed example scripts live under system.file("examples", package = "dragmapr"). To exercise the full package surface non-interactively:

source(system.file("examples", "smoke_examples.R", package = "dragmapr"))

Shiny examples launch interactive apps and must be run separately. See the Shiny workflows vignette for a full walkthrough, or run any example directly:

if (interactive()) {
  shiny::runApp(system.file("examples", "shiny_draggable_plot.R",   package = "dragmapr"))
  shiny::runApp(system.file("examples", "shiny_custom_labels.R",    package = "dragmapr"))
  shiny::runApp(system.file("examples", "shiny_draggable_export.R", package = "dragmapr"))
  shiny::runApp(system.file("examples", "shiny_spatial_studio.R",   package = "dragmapr"))
  shiny::runApp(system.file("examples", "shiny_static_export.R",    package = "dragmapr"))
}

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.