What if it only took a few clicks to create a map like this?
Choropleth maps color geographic areas, such as states or counties, based on their data values. These maps are a popular way to depict patterns by location and are commonly found in Urban Institute blog posts and reports. While numerous tools can generate choropleths, this post will describe an internal application we built that makes it as easy as a few simple clicks to produce a good-looking, Urban-branded map, such as the one above.
In the past few years, Urban has developed R packages, such as urbnthemes and urbnmapr, that empower researchers to easily create charts and maps that meet our data visualization design standards. These packages help simplify and standardize making visually appealing graphics for R programmers. We recently built a user interface on top of urbnthemes and urbnmapr using Shiny, an R package for creating interactive web applications, to make mapmaking easy and accessible for Urban staff who either don’t program in R or have no programming experience at all.
What does the app do?
The Shiny app provides a simple, user-friendly interface for making a choropleth map of the US.
Here are the steps users must follow to create their map:
(1) Specify the type of map desired. Options here are for state- or county-level maps, with the ability to include US territories.
(2) Upload the dataset. The dataset must be a comma-separated value (CSV) file. The file should include a header row of variable names and at least two columns: one that contains some way of uniquely identifying geographies and one with the values to be applied to the map. Users can view an example data file if they are unclear on what their dataset should look like.
(3) Enter the name of the variable with the values to be mapped.
(4) Specify the geographic identifier used in the data. If making a state-level map, users can choose between names, abbreviations, or state FIPS codes. If they’re making a county-level map, users must use county FIPS codes to identify their observations. The options displayed here are dynamically determined based on the map type the user selected in step 1.
(5) Enter the name of the column in the dataset that contains the geographic identifier specified in step 4, which will tell R how to join the user’s data to the appropriate urbnthemes dataset.
(6) (Optional) Users can also choose to add state abbreviation labels to their map, such as in the example map below.
Finally, users click on the “Map it!” button to generate their map.
What does the app output?
After completing the steps above, the app displays a choropleth map based on the user’s data. To export the map, users click a button to download a PDF of the image to their computer. Users must download a PDF file — rather than an image file, such as a JPEG or PNG — because these maps usually still have to be edited and tweaked by the communications team in programs like Adobe Illustrator before they are published. While urbnthemes does a lot of the heavy lifting in applying Urban’s styles, the package has a few limitations that require manual adjustments. A PDF allows the maps to be handed off to someone on the communications team to make those final changes.
The Shiny app also displays R code that can be run to re-create the map. The generated code can be used by R programmers to re-create the map easily or tweak it to further customize their plot.
How to build a Shiny app and deploy it
Getting an app up and running with Shiny is quick and straightforward. After installing the Shiny package, a script called app.R needs to be created. In this script are three components that every Shiny app must have:
· a user interface object
· a server function
· a call to the shinyApp function
The user interface object contains all the code related to how the app looks and feels. Any inputs such as dropdown menus, file uploads, radio buttons, or checkboxes are defined here. The server function executes R code that, in this case, returns a choropleth map. Finally, the call to shinyApp is what creates a Shiny application based on the defined user interface and server functions. For a more detailed tutorial on how to build a Shiny app, please see here.
To run the app locally, one just needs to execute the runApp() command from within the application directory. Allowing others to access the app, however, requires having a Shiny server. A Shiny server allows users to easily host their own R Shiny applications for others to use. At Urban, our R Shiny server is hosted on an Amazon Web Services (AWS) Elastic Cloud Compute (EC2) instance, and we use a Docker build of the Shiny server to make deployment easy and reliable.
If you would like to run our app yourself or see how we built it, you can download the source code for it from here.
Why build a (Shiny) app?
We chose Shiny to create this tool for two reasons. First, Shiny is an easy way to quickly create an interactive web application without having to write a bunch of HTML or use a complicated web framework. The second advantage of using Shiny is that, as a R-based framework, it’s easy to use with other R packages, such as urbnthemes and urbnmapr. Shiny allows both web application development and data visualization to be executed in R.
A point-and-click web app provides numerous benefits, notably its accessibility to non-R users. Those unfamiliar with coding in R — such as our communications team and researchers, who rely on Excel for graphing — can leverage urbnthemes and urbnmapr to easily create styled maps. For those who do use R, the app provides a snippet of code that can be used for further customization or added to a larger script.
Another benefit of having a web app is its ease of use. Users only have to spend a few seconds making their selections, and then they can see their map. This approach is faster than writing code from scratch if someone wants to create a simple visual. And having an interface with a few predetermined inputs doesn’t necessarily mean sacrificing flexibility. As noted above, users can choose between various types of maps, upload different types of data, and use different geographic identifiers in their dataset.
Future enhancements
The current iteration of this app is just a starting point for introducing users to the world of mapmaking in R. One piece of additional functionality we’d like to incorporate into this tool is the ability to create single-state, county-level maps. Currently the app only allows users to generate maps of the entire US but sometimes researchers need to make more locally-focused maps.
The Shiny app will also evolve as updates are made to the underlying urbnmapr and urbnthemes packages. Current issues include improving the legend styling and providing different options for displaying DC on a map. As improvements are made, we will include this new functionality in the Shiny app.
Shiny provides a powerful means for easily creating interactive web applications from within the R ecosystem. We hope apps like these will allow other tools we have built — such as urbnmapr and urbnthemes — to reach broader audiences, so more people can be empowered to create beautiful, flexible, and reproducible data visualizations.
