At the Urban Institute, we are always looking for ways to visualize data. Whether I’m looking for spatial trends or creating graphics for a report, I often create a map. Making maps to explore and communicate the geographic distribution of data should be simple and fun, but it’s often challenging. Aaron Williams, Kyle Ueyama, and I created an R package, urbnmapr, to solve this problem and make basic mapping more accessible at Urban.
At Urban, we frequently create maps of the US to include in blog posts and reports. There are a few basic elements needed before a map of the US is ready to go. For instance, Alaska and Hawaii are usually scaled and shifted so they can appear next to the contiguous United States. Geographic data can also be large, clunky, and appear in several different formats, such as shapefile, GeoJSON, or KML (Keyhole Markup Language). These files often need to be converted into a certain format so they can work best with your data visualization software tool of choice. I needed shapefiles I could use in R, specifically with ggplot2. As I made more maps, I was constantly moving files around and replicating my own efforts when all I wanted was to make a simple map.
Our package: urbnmapr
urbnmapr is the first R package developed by and for Urban staff. It aims to simplify and standardize the process of making state and county choropleth maps in R. Choropleth maps, like the example below, shade different geographic units (e.g., countries, states, or counties) based on data values. In Urban’s Housing Finance Policy Center, we wanted to see how the share of Ginnie Mae loans varies across states:
The R package allows users to load in shapefiles, equipped with geographic identifiers for merging with other data, with just one line of code. Combined with Aaron Williams’s Urban Institute theme package and Urban’s mapping guide, this tool makes it simple to build Urban-styled maps as research aids or as final products in a publication. Even users with limited programming or mapping experience can quickly make custom maps in R.
Making your first map
To use the package, first install it from Github (if you don’t yet have devtools installed, make sure you install.packages('devtools') first):
From there, you can easily load and plot the shapefiles you need using ggplot2.
Merging your data
The state dataset includes state names, abbreviations, and Federal Information Processing Standards (FIPS) codes — unique numeric identifiers for each county and state. The county dataset includes all the state variables plus county names and FIPS codes, making it easy to merge with the data you are working with, whether they include names or codes. With just a few additional lines of code, you can create a custom choropleth map.
Advantages of Mapping in R
There are a few characteristics I love about this package and making maps in R in general:
1. Tidy data. Using tidy spatial data opens doors for quick and easy data wrangling. Say you want to map every county in one state. Using the R library (dplyr), you can easily create a map of California:
It’s also easy to use the full layering capabilities of ggplot2. For county maps, it is standard Urban style to add a thicker white border around states to make the maps easier to read:
2. Reusable code. Making maps programmatically saves time. My team is constantly updating our data so when new data come in, we can quickly input the data and produce a new map in seconds.
I used maps I made with urbnmapr in a recent report I wrote with my colleagues from the Housing Finance Policy Center. We were looking for US counties that have the highest share of homes sold for $70,000 or less. As we wrote the report and received feedback, we changed our criteria and sales thresholds. Whenever we had new data, all I had to do was change a few lines of code and could instantly have a new map ready to go.
3. Reusable layout. It is easy to produce and export maps that are identical in layout and size. I often want to make several maps that are almost identical or that fit in a certain template, like a PowerPoint slide. Because I use the same uniform geographic data and can specify every feature of the map in my code, I can export maps designed to fit my needs.
4. Expandable package. Our package-based solution allows us to keep improving and enhancing the tools we can share. We have already made several improvements since our first version of urbnmapr, and the package’s structure makes it possible to take input from other researchers at Urban on what they need from the package and improve it. We have already added US territories and additional data for labeling states and cities based on researcher feedback. In the future, we hope to expand the geographic levels we offer and incorporate new formats of spatial data (such as “simple features”).
Mapmaking can be a difficult, laborious process, especially when the data and design are constantly changing. Our R package is open to anyone, and all the code is publicly available on GitHub. I hope it lowers the barrier to entry for people who want to analyze and share insights from geospatial data.
