state_choropleth: Create a choropleth map using U.S. state level data

In choroplethr: Create Color-Coded Choropleth Maps in R

Create a choropleth map using U.S. state level data

Description

To see the list of allowed state names, see choroplethr::state.regions.

Usage

state_choropleth(
  df,
  geoid.name = "region",
  geoid.type = "auto",
  value.name = "value",
  style = "geographic_bigdc",
  num_colors = 7,
  color.max = NULL,
  color.min = NULL,
  na.color = "grey",
  custom.colors = NULL,
  nbreaks = 5,
  zoom = NULL,
  projection = "albers",
  border_color = "grey15",
  border_thickness = 0.2,
  background_color = "white",
  gridlines = FALSE,
  latlon_ticks = FALSE,
  whitespace = TRUE,
  label = NULL,
  label_text_size = 2.25,
  label_text_color = "black",
  label_box_color = "white",
  ggrepel_options = list(force = 0.01, box.padding = 0.15, label.padding = 0.15,
    max.overlaps = Inf),
  legend = NULL,
  legend_position = "right",
  title = NULL,
  return = "plot"
)

Arguments

df	A dataframe containing U.S. state level data
geoid.name	The variable that identifies each state
geoid.type	How the variable given by geoid.name specifies each state (full name, abbreviation, etc). The allowed geoid.type are given in choroplethr::state.regions. If "auto", the function will try to automatically determine geoid.type.
value.name	The name of the variable you wish to plot.
style	Either "geographic" for a literal map of US states, "geographic_bigdc" to make Washington DC more visible, or "hexgrid" for a stylized hexagonal tile map. Note: projection = 'mercator' is suggested when using the hexgrid map.
num_colors	The number of colors you want in your graph when plotting continuous data. If num_colors > 1, the variable in question will be divided into quantiles and converted into a factor with that many levels. If num_colors = 1, a continuous color gradient will be used; if num_colors = 0, a diverging color gradient will be used (useful for visualizing negative and positive numbers). Use color.max and color.min to control the range of colors displayed. num_colors is ignored when plotting categorical data.
color.max	The color of the highest value in your data. Ignored if the plotted variable is categorical.
color.min	The color of the lowest value in your data. Ignored if the plotted variable is categorical.
na.color	The color you want to assign for regions with missing data
custom.colors	A vector of valid R color terms of the to use for the map when plotting factor variables. The length of this vector must match the number of levels in your factor variable, or num_colors for a continuous variable that will be discretized by the function, and the order should match the order of the levels of in your factor variable.
nbreaks	The number of breaks you wish to show in the legend when using a continuous color scale. Ignored if num_colors > 1.
zoom	An optional vector of states to zoom in on, written in the same manner as geoid.name.
projection	One of the following: "cartesian", "mercator", "robinson", or "albers", for equirectangular, Mercator, Robinson, and Albers Equal Area projections, respectively. When using the Mercator projection for world maps, setting limits_lon is recommended to prevent exaggeration of the size of Antarctica.
border_color	The color of the borders on your map
border_thickness	The thickness of the borders on your map
background_color	The background color of your map
gridlines	Should gridlines appear on your map?
latlon_ticks	Should lat/lon tick marks appear on the edge of your map?
whitespace	Add some blank space to the sides of your map? For some projections, this must be set to FALSE in order for lat/lon ticks and display correctly.
label	The name of variable you wish to use to label your map; must be one of the variables that appears in the spatial dataframe just prior plotting (use return = 'sf' to see this dataframe), and in general, can be any of the allowed geoid.type. This function uses ggplot2::geom_label_repel to create the labels and ensure that they do not overlap.
label_text_size	The size of the text that will appear in each label
label_text_color	The color of the text that will appear in each label
label_box_color	The color of the box around each label
ggrepel_options	A list containing additional arguments to be passed to geom_label_repel (see ?ggplot2::geom_label_repel)
legend	A title for your legend; if NULL, value.name will be used.
legend_position	The position of your legend relative to the rest of the map; can be "top", "bottom", "left", or "right".
title	A title for your plot; if NULL, no title will be added.
return	If "plot", the function will return the requested map as a ggplot object. If "sf", the function will return the spatial dataframe used to draw the map (useful if you wish to customize the map yourself).

Examples

# Plot continuous state level data:
data(df_state_demographics)
state_choropleth(df = df_state_demographics,
                 geoid.name = 'region',
                 geoid.type = 'name.lower',
                 value.name = 'population',
                 title  = "U.S. State Population",
                 legend = "Population")

# Plot categorical data with custom colors:
data("df_president")
state_choropleth(df = df_president,
                 geoid.name = 'region',
                 geoid.type = 'name.lower',
                 value.name = 'value',
                 title  = "2012 US Presidential Election Results",
                 legend = "Candidate",
                 custom.colors = c('blue4', 'red3'),
                 border_color = 'lightgrey')

# Label states and pass additional arguments to ggrepel
state_choropleth(df = df_president,
                 geoid.name = 'region',
                 geoid.type = 'name.lower',
                 value.name = 'value',
                 title  = "2012 US Presidential Election Results",
                 legend = "Candidate",
                 custom.colors = c('blue4', 'red3'),
                 border_color = 'lightgrey',
                 label = 'state.abb',
                 label_text_size = 4,
                 ggrepel_options = list(label.r = 0, force = 0.02))
                 
# Use a styled hexagonal tile map instead of actual state shapes:
state_choropleth(df = df_president,
                 style = 'hexgrid',
                 projection = 'mercator',
                 geoid.name = 'region',
                 geoid.type = 'name.lower',
                 value.name = 'value',
                 title  = "2012 US Presidential Election Results",
                 legend = "Candidate",
                 custom.colors = c('blue4', 'red3'),
                 border_color = 'lightgrey',
                 label = 'state.abb',
                 label_text_size = 3)

choroplethr documentation built on June 27, 2025, 1:07 a.m.