Creating Maps with viz_map()

📖 Introduction

The viz_map() function creates choropleth maps - geographic maps where regions are colored by data values. They’re perfect for showing how metrics vary across countries, states, or other geographic areas.

library(dashboardr)
library(dplyr)

Important: Maps require data with geographic identifiers (ISO country codes, state abbreviations, etc.). Unlike other visualizations, maps typically can’t use GSS data directly since GSS regions don’t map to standard geographic codes. The examples below use hypothetical geographic datasets.

🌍 Basic World Map

Country-Level Data

Your data needs a column with geographic codes that match the map:

# Sample country data
country_data <- data.frame(
  country_code = c("USA", "GBR", "DEU", "FRA", "JPN", "CHN", "BRA", "AUS"),
  happiness_score = c(7.0, 7.2, 6.9, 6.5, 5.9, 5.1, 6.3, 7.3)
)

plot <- viz_map(
  data = country_data,
  join_var = "country_code",
  value_var = "happiness_score",
  map_type = "custom/world",
  title = "Happiness Score by Country"
)

plot

Color Gradients

Control the color scale with color_palette - provide low and high colors:

plot <- viz_map(
  data = country_data,
  join_var = "country_code",
  value_var = "happiness_score",
  map_type = "custom/world",
  title = "Happiness Score",
  value_label = "Score",
  color_palette = c("#FEE5D9", "#A50F15")  # Light to dark red
)

plot

🗺️ US State Maps

State-Level Data

Use state abbreviations or FIPS codes:

# State data with abbreviations
state_data <- data.frame(
  state = c("CA", "TX", "FL", "NY", "PA", "IL", "OH", "GA", "NC", "MI"),
  population_millions = c(39.5, 29.1, 21.5, 20.2, 13.0, 12.8, 11.8, 10.7, 10.4, 10.0)
)

plot <- viz_map(
  data = state_data,
  join_var = "state",
  value_var = "population_millions",
  map_type = "countries/us/us-all",
  title = "US Population by State",
  color_palette = c("#EBF5FB", "#1A5276")
)

plot

🏷️ Labels and Tooltips

Basic Tooltips

By default, maps show the region name and value on hover. Add more columns to the tooltip with tooltip_vars:

state_detailed <- data.frame(
  state = c("CA", "TX", "FL", "NY"),
  value = c(100, 80, 60, 90),
  growth = c(2.1, 3.5, 2.8, 1.2),
  label = c("California", "Texas", "Florida", "New York")
)

plot <- viz_map(
  data = state_detailed,
  join_var = "state",
  value_var = "value",
  map_type = "countries/us/us-all",
  tooltip_vars = c("label", "value", "growth"),
  title = "State Metrics",
  value_label = "Score"
)

plot

Parameter	Description	Example
`tooltip_vars`	Columns to include in tooltip	`c("name", "value", "change")`
`tooltip_prefix`	Text before main value	`"$"`, `"Score: "`
`tooltip_suffix`	Text after main value	`"%"`, `" million"`
`value_label`	Label for the legend	`"Population"`, `"Score"`

plot <- viz_map(
  data = state_data,
  join_var = "state",
  value_var = "population_millions",
  map_type = "countries/us/us-all",
  title = "US Population",
  value_label = "Population (millions)",
  tooltip_suffix = " million people",
  color_palette = c("#DEEBF7", "#08519C")
)

plot

🇪🇺 European Maps

european_data <- data.frame(
  country = c("DE", "FR", "GB", "IT", "ES", "PL", "NL", "BE"),
  gdp_per_capita = c(46000, 40000, 42000, 32000, 27000, 15000, 52000, 45000)
)

plot <- viz_map(
  data = european_data,
  join_var = "country",
  value_var = "gdp_per_capita",
  map_type = "custom/europe",
  title = "GDP per Capita in Europe",
  value_label = "GDP per Capita (€)",
  tooltip_prefix = "€",
  color_palette = c("#F7FCB9", "#31A354")
)

plot

📋 Map Types Reference

Map Type	Coverage	Join Variable
`"custom/world"`	All countries	ISO 3166-1 alpha-3 (USA, GBR, DEU)
`"countries/us/us-all"`	US states	State abbreviations (CA, TX, NY)
`"custom/europe"`	European countries	ISO 3166-1 alpha-2 (DE, FR, GB)
`"countries/us/custom/world"`	World regions	Various codes

🌐 Real-World Examples

Survey Response Rates by State

response_data <- data.frame(
  state = c("CA", "TX", "FL", "NY", "PA", "IL", "OH", "GA", "NC", "MI",
            "NJ", "VA", "WA", "AZ", "MA", "TN", "IN", "MO", "MD", "WI"),
  response_rate = c(45, 38, 42, 51, 44, 47, 39, 35, 41, 43,
                    48, 46, 52, 37, 55, 36, 40, 38, 49, 44)
)

plot <- viz_map(
  data = response_data,
  join_var = "state",
  value_var = "response_rate",
  map_type = "countries/us/us-all",
  title = "Survey Response Rate by State (%)",
  color_palette = c("#FFEDA0", "#BD0026")
)

plot

Global Satisfaction Scores

global_survey <- data.frame(
  country = c("USA", "CAN", "MEX", "GBR", "DEU", "FRA", "JPN", "AUS", "BRA", "IND"),
  satisfaction = c(7.2, 7.5, 6.8, 7.1, 6.9, 6.5, 6.2, 7.4, 6.6, 5.8)
)

plot <- viz_map(
  data = global_survey,
  join_var = "country",
  value_var = "satisfaction",
  map_type = "custom/world",
  title = "Customer Satisfaction by Country",
  value_label = "Satisfaction Score",
  tooltip_suffix = " / 10",
  color_palette = c("#FEE8C8", "#E34A33")
)

plot

📁 Using with create_content()

Basic Integration

content <- create_content(data = state_data, type = "map") %>%
  add_viz(
    join_var = "state",
    value_var = "population_millions",
    map_type = "countries/us/us-all",
    title = "Population Distribution"
  )

content %>% preview()

Preview

Population Distribution

Multiple Maps with Different Metrics

multi_metric <- data.frame(
  state = c("CA", "TX", "FL", "NY", "PA"),
  population = c(39.5, 29.1, 21.5, 20.2, 13.0),
  income = c(75000, 60000, 55000, 70000, 58000),
  satisfaction = c(7.2, 6.8, 7.0, 6.5, 6.9)
)

content <- create_content(data = multi_metric, type = "map", map_type = "countries/us/us-all") %>%
  add_viz(
    join_var = "state",
    value_var = "population",
    title = "Population",
    tabgroup = "Metrics"
  ) %>%
  add_viz(
    join_var = "state",
    value_var = "income",
    title = "Median Income",
    tabgroup = "Metrics"
  ) %>%
  add_viz(
    join_var = "state",
    value_var = "satisfaction",
    title = "Satisfaction",
    tabgroup = "Metrics"
  )

💡 Data Preparation Tips

Finding the Right Codes

Maps use standardized geographic codes. Common formats:

Region Type	Code Format	Examples
Countries (world)	ISO 3166-1 alpha-3	USA, GBR, DEU, FRA
Countries (Europe)	ISO 3166-1 alpha-2	US, GB, DE, FR
US States	USPS abbreviations	CA, TX, NY, FL

Handling Missing Regions

Regions without data appear in a neutral color:

# Only 5 states - others will be gray
partial_data <- data.frame(
  state = c("CA", "TX", "FL", "NY", "WA"),
  metric = c(100, 90, 85, 95, 80)
)

plot <- viz_map(
  data = partial_data,
  join_var = "state",
  value_var = "metric",
  map_type = "countries/us/us-all",
  title = "Partial Coverage Map",
  value_label = "Score",
  null_color = "#EEEEEE",  # Color for missing regions
  color_palette = c("#C6DBEF", "#084594")
)

plot

🔍 When to Use Maps

Use maps when: - Showing geographic patterns - Regional comparisons are important - Audience thinks spatially about the data - Location context adds meaning

Use bar charts instead when: - Precise comparisons matter more than geography - Data isn’t inherently geographic - You have many small regions (hard to see)

📚 See Also

?viz_map - Full function documentation
vignette("heatmap_vignette") - For non-geographic grids
vignette("content-collections") - For dashboard integration

⚠️ Note on Map Data

Maps require the Highcharts Maps module, which is included with dashboardr. The map geometries are loaded from Highcharts’ CDN when the dashboard is viewed. For offline use or custom boundaries, additional configuration may be needed.