Install R and RStudio

The data analysis software that we will be using in this code-through are the open source software products R and RStudio. Therefore, you must have both installed on your device to follow along.

If you do not have R and RStudio on your device, you can download the appropriate software for your device at the following links: R and RStudio.

However, if you already have R and RStudio installed, then you can skip ahead to the next section.

Install R-Markdown.

One of the most useful features of RStudio is its ability to create fancy documents known as R-Markdown files that end with .rmd. These files can then be deployed to .html files that can be sent to others to explore your data. You can also publish these files online to a web server utilizing RPubs within RStudio.

To begin, you will need to have the R Markdown package installed on your computer. To check whether you have the package installed, you can enter the following code into your console in RStudio:

installed.packages("rmarkdown")

If you do not have R Markdown installed, then you will enter the following code:

install.packages("rmarkdown")

Set Up Interactive HTML Document

Once R Markdown is successfully installed, we can begin the process of creating our HTML document.

Following the instructions on RPub’s Introduction to R Markdown you can open up the dialog box to create a New File and then a New R Markdown.

This will then present you with a dialog box like the following:

In this dialogue box, you want to select the Document option on the left hand side of the screen. If you would like, you can also enter a title in the title box and your name in the author box. If not, you can enter these later. The most important thing here is to select the HTML default output format to create an interactive webpage.

Once these options are selected, click okay and you will be taken to the document in RStudio where you will see the following screen:

There is quite a lot of information here, including a link to RStudio’s myriad of information on R Markdown. I would suggest clicking the Knit button at the top of the screen to get an idea of how your basic HTML document will look and preview all of the features that can be tailored to your individual needs. In addition, you can preview your options to publish your file online using RPubs by clicking the blue circular figure next to ‘Run’.

After you have completed previewing the HTML file and publishing options, return to the main RStudio window where we will examine the document.

First, you will notice the YAML header at the top of the page:

If you did not enter your name or the title in dialog box to create the file, then the default is for the document to contain just 2 elements in the YAML header:

1. title
2. output

The output element is the most critical because it is needed to tell RStudio to transform the default .rmd file into an HTML document.

However, we can also customize this header a bit to look something like this:

These changes provide:

1. A detailed title so that viewers of your HTML web page document can understand the subject immediately.

2. An author for the document so that you can be credited for the document and/or contacted about any issues with the document.

3. A date to give an estimate of how recently the information presented has been curated.

4. A fancier format for your HTML document. RMarkdown is compatible with quite a few different templates. Andrew Zieffler created an awesome gallery of many of the different templates available that you can view by clicking here. Specifically, the theme used for this code-through is presented in the image and can be accessed by entering the following code in your RStudio Console and then setting your YAML header with the appropriate settings:

install.packages("rmdformats")

Code Chunks

Following the YAML header at the top of your document, the next section of the file that you see is what’s known as a code chunk:

The sample codes detailing how to check for installed packages and install packages included in this code-through are all examples of code chunks. These chunks are where you will run your R codes in R Markdown and they are essential to all data analysis.

For this tutorial, we will have several code chunks to do everything from running packages to defining our data set to graphing our choropleth map.

Sections

The sections element of the document is relatively self-explanatory and serves as the way that you will “break down” your findings in your HTML document to make your data easy for you to navigate and for your viewers to understand. As shown in the image below, these headers are defined in RMarkdown by using the ‘#’ sign known as a ‘pound sign’, ‘number sign’, or more recently, a ‘hashtag’:

Plain Text

As implied by the name, plain text is the basic text that is written in a RMarkdown file to provide details, answers, or any other form of text needed to accompany the code chunks. This text can be stylized with asterisks, html code, and other features as mentioned on the RMarkdown cheat sheet to enhance its appearance.

Packages

Before we can begin our data analysis, we need a few tools. Most importantly, we need to install the packages we will be using to create our choropleth map:

install.packages ("tidycensus")
install.packages("tidyverse")
install.packages("viridis")
install.packages("DT")
install.packages("dplyr")
install.packages("leaflet")
install.packages("pander")
install.packages("stringr")
install.packages("sf")
install.packages("htmltools")

Library

Once these packages have been installed, we will add them to our library with the following code chunk:

#Library
library(tidycensus)
library(tidyverse)
library(viridis)
library(DT)
library(dplyr)
library(leaflet)
library(pander)
library(stringr)
library(sf)
library(htmltools)

Data

Now that we have installed R, RStudio, RMarkdown, and all of our packages, we’re ready to begin our data analysis.

First, we’re going to load the data from the Census Bureau.

In order to do this, you will need to create a Census API Key from the census website:

After submitting the form, you will receive an email with your code that you will enter into the following code:

census_api_key("YOUR_CENSUS_API_KEY_HERE")

Preview Data

Once you have set your API key, you can now query data from any of the Census Bureau’s available American Community Surveys. For the purposes of this tutorial, we will be accessing data from the ACS’s 5 year estimates for 2017. To preview this data enter the following code:

# Preview Data
VarPreview <- load_variables( 2017, "acs5", cache=TRUE )

# Convert all letters to upper case to make searching easier
VarPreview$concept <- toupper(VarPreview$concept)

# Search for households that have one or people under 18
ChildHouseholds <-  VarPreview %>%
  mutate( contains.ChildHouseholds = grepl( "PEOPLE UNDER 18", concept ) ) %>% 
  # Create new variable with Mutate that has PEOPLE UNDER 18 in title using grepl
  filter( contains.ChildHouseholds )

# Preview data
head(ChildHouseholds) %>% pander()

A review of the data indicates that the variable that lists all households is B11005_001 and the variable that lists all households with one or more people under 18 (children) is B11005_002. Therefore, this will be the variable that we will use to map households with children on our choropleth map.

Next, we will prepare our data set to contain information on households with children under 18 and total households for every state and the District of Columbia in the United States:

# Data Set

dat <- c(ChildHouseholds = "B11005_002", TotalHouseholds = "B11005_001")
CenDF <- get_acs(geography="state", year=2017, survey="acs5", 
                  variables= dat, geometry=T)

head(CenDF) %>% pander()

Now, that we have the data we need, we will make a few changes to prepare for mapping. This will include removing the margin of error moe from our data set, shifting child households and total households to their own columns, and finding the percentage of households that have children for each state and D.C.:

library(tidyr)
CenDF <- CenDF %>% 
  select(- moe) %>%  
  spread(variable, estimate) %>% #Spread moves rows into columns
  mutate(PercentageHHWithKids= round((ChildHouseholds/TotalHouseholds)*100, 2)) %>% #mutate finds percentage of households with children 
  arrange(PercentageHHWithKids) # Orders by percentage

CenDF %>% pander()

Details

Before we plot our data set above, we need to decide on a few critical details: the color scheme we would like for our map, the interactive information we want to display, and our information dialogue box.

As detailed in this guide on Leaflet for R, there are a variety of color schemes and options that can be customized for our mapping needs. In this tutorial, we will use the colorNumeric function and a palette of blue hues. Many leading data visualization specialists such as Cole Nussbaumer Knaflic in her book ‘Storytelling with Data’ recommend creating charts in blue whenever possible because it is an easy-to-view color for individuals with color blindness and the range of hues allows for quick comparison across categories.

Therefore, we will set our pallete as Blues from Color Brewer 2 and set our domain to the variable we created above PercentageHHWithKids.

pal <- colorNumeric(palette = "Blues", domain = CenDF$PercentageHHWithKids)

Now that we have our color scheme set, we need to decide what information we want to display when people click on our interactive map. For our purposes, just two fields will suffice: the name of the state and the percentage of households with children.

We will define these details below and preview the output of our popup:

popup <- paste0("<strong>", CenDF$NAME, 
                   "</strong><br />Percentage of Households with Children: ", CenDF$PercentageHHWithKids, "%")
head(popup)

## [1] "<strong>District of Columbia</strong><br />Percentage of Households with Children: 21.51%"
## [2] "<strong>Maine</strong><br />Percentage of Households with Children: 25.91%"               
## [3] "<strong>Vermont</strong><br />Percentage of Households with Children: 26.09%"             
## [4] "<strong>Montana</strong><br />Percentage of Households with Children: 27.26%"             
## [5] "<strong>Florida</strong><br />Percentage of Households with Children: 27.56%"             
## [6] "<strong>West Virginia</strong><br />Percentage of Households with Children: 27.84%"

For our information dialogue box we will use the htmltools package to customize a message:

library(htmltools)
MapInfo <- tags$p(tags$style("<p {font-size:12px} />"),
            tags$b("Percentage of households with children by state, click on states to view details"))

Mapping Data

Finally, we can put all these steps together to create our map with the following code:

CenDF %>% # Inputs data set
    leaflet(width = "100%") %>% # Interactive mapping package
    addProviderTiles(provider = "CartoDB.Positron") %>% # Changes base map
    setView(-98.483330, 38.712046, zoom = 4) %>% # Zooms into the United States
    addPolygons(popup = ~ popup,
                stroke = FALSE,
                smoothFactor = 0,
                fillOpacity = 0.7,
                color = ~ pal(PercentageHHWithKids)) %>% # Customizes map
    addLegend("bottomright", 
              pal = pal, 
              values = ~ PercentageHHWithKids,
              title = "Percentages",
              opacity = 1) %>% # Creates legend
    addControl(MapInfo, position = "bottomleft") #Creates info dialogue box

The CenDF line of code calls for our data set to be pooled into the leaflet() package that maps our data in an interactive format.

Once this occurs, we then tinker with leaflet’s settings to create our choropleth map. The first thing that we alter is leaflet’s base map. By default, leaflet uses the basic OpenStreetMap displayed below:

leaflet(width = "100%") %>% 
setView(-98.483330, 38.712046, zoom = 4) %>% 
addTiles()

While this map is acceptable for use, altering it to the more customized CartoDB.Positron map gives us a cleaner, less-busy base map:

 leaflet(width = "100%") %>%
    addProviderTiles(provider = "CartoDB.Positron") %>% 
    setView(-98.483330, 38.712046, zoom = 4)

The next line of code zooms our map into the contiguous United States:

setView(-98.483330, 38.712046, zoom = 4)

Now, we add the details we created above by entering our popup and pallette preferences into the addPolygons() function:

    addPolygons(popup = ~ popup,
                stroke = FALSE,
                smoothFactor = 0,
                fillOpacity = 0.7,
                color = ~ pal(PercentageHHWithKids))

Last, but not least, we create a legend for our map:

    addLegend("bottomright", 
              pal = pal, 
              values = ~ PercentageHHWithKids,
              title = "Percentages",
              opacity = 1)

And voila!

CenDF %>% 
    leaflet(width = "100%") %>% 
    addProviderTiles(provider = "CartoDB.Positron") %>%
    setView(-98.483330, 38.712046, zoom = 4) %>%
    addPolygons(popup = ~ popup,
                stroke = FALSE,
                smoothFactor = 0,
                fillOpacity = 0.7,
                color = ~ pal(PercentageHHWithKids)) %>%
    addLegend("bottomright", 
              pal = pal, 
              values = ~ PercentageHHWithKids,
              title = "Percentages",
              opacity = 1) %>%
    addControl(MapInfo, position = "bottomleft")

We now have an interactive map that displays our census data for each state. Specifically, we can clearly see that Maine is the state with the lowest percentage of households with children (25.91%) while Utah is the state with the highest percentage of households with children (41.74%)!

Videos

This video created by the United States Census Bureau provides a lot of insights on the American Community Survey and its many uses for data analysis and policymaking:

This DataGem video from the Census Bureau provides additional details on ways to access the survey data:

Readings

American Community Survey: Website from the U.S. Census Bureau that provides details on the survey and access to data.

TidyCensus: Details and tips on how to use the tidycensus R package.

Leaflet for R: Details and tips on how to use the leaflet R package.

TidyCensus and Leaflet Example One: This blog post by Julia Silge was the inspiration for this code-through and provides other great examples of combining the tidycensus and leaflet packages to create interactive choropleths.

TidyCensus and Leaflet Example Two: Similar to this code-through, this tutorial by Kier O’Neil was also based off of Julia Silge’s blog post and gives other examples of ways to work with tidycensus and leaflet together.

Interactive Choropleth Maps: This tutorial video and website provides great tips and tricks on ways to create choropleth maps in R. However, this specific tutorial uses tigris to get shapefiles. This is helpful if you’re using a data set that does not already have the shapefiles built in, but requires a few extra steps beyond using the tidycensus package that the site details beautifully.