getting-data.qmd

---
output: 
  html_document:
    includes:
      in_header: analytics.html  	
    css: styles.css
    code_folding: show
    toc: TRUE
    toc_float: TRUE
    pandoc_args:
      "--tab-stop=2"
---

<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato" />

::: {#header}
<img src="intro-to-r/images/urban-institute-logo.png" width="350"/>
:::

```{r echo = FALSE}
# source(here::here("getting-data", "census_api_key.R"))
```

```{r markdown-setup, include=FALSE}

knitr::opts_chunk$set(fig.path = "intro-to-r/www/images/")
knitr::opts_chunk$set(message = FALSE)
knitr::opts_chunk$set(warning = FALSE)
knitr::opts_chunk$set(echo = TRUE)


options(scipen = 999)
```

# Introduction

This guide outlines some useful workflows for pulling data sets commonly used by the Urban Institute.

## `library(tidycensus)`

`library(tidycensus)` by Kyle Walker ([complete intro here](https://walkerke.github.io/tidycensus/)) is the best tool for accessing some Census data sets in R from the Census Bureau API. The package returns tidy data frames and can easily pull shapefiles by adding `geometry = TRUE`.

You will need to [apply for a Census API key](https://api.census.gov/data/key_signup.html) and [add it to your R session](https://walkerke.github.io/tidycensus/articles/basic-usage.html). Don't add your API key to your script and don't add it to a GitHub repository!

Here is a simple example for one state with shapefiles:

```{r tidycensus}
library(tidyverse)
library(purrr)
library(tidycensus)

# pull median household income and shapefiles for Census tracts in Alabama
get_acs(geography = "tract", 
				variables = "B19013_001", 
				state = "01",
				year = 2015,
				geometry = TRUE,
				progress = FALSE)
```

Smaller geographies like Census tracts can only be pulled state-by-state. This example demonstrates how to iterate across FIPS codes to pull Census tracts for multiple states. The process is as follows:

1.  Pick the variables of interest
2.  Create a vector of state FIPS codes for the states of interest
3.  Create a custom function that works on a single state FIPS code
4.  Iterate the function along the vector of state FIPS codes with `map_df()` from `library(purrr)`

Here is an example that pulls median household income at the Census tract level for multiple states:

```{r tidycensus-iteration}
# variables of interest
vars <- c(
  "B19013_001"  # median household income estimate
)

# states of interest: alabama, alaska, arizona
state_fips <- c("01", "02", "04")
	
# create a custom function that works for one state
get_income <- function(state_fips) {
	
	income_data <- get_acs(geography = "tract", 
												 variables = vars, 
												 state = state_fips,
												 year = 2015)
	
	return(income_data)
	
}

# iterate the function
map_df(.x = state_fips, # iterate along the vector of state fips codes
			 .f = get_income) # apply get_income() to each fips_code  
```

`library(tidycensus)` works well with `library(tidyverse)` and enables access to geospatial data, but it is limited to only some Census Bureau data sets. The next package has less functionality but allows for accessing any data available on the Census API.

<br>

## `library(censusapi)`

`library(censusapi)` by Hannah Recht ([complete intro here](https://cran.r-project.org/web/packages/censusapi/vignettes/getting-started.html)) can access any published table that is accessible through the Census Bureau API. A full listing is available [here](https://api.census.gov/data.html).

You will need to [apply for a Census API key](https://api.census.gov/data/key_signup.html) and [add it to your R session](https://cran.r-project.org/web/packages/censusapi/vignettes/getting-started.html). Don't add your API key to your script and don't add it to a GitHub repository!

Here is a simple example that pulls median household income and its margin of error for Census tracts in Alabama:

```{r censusapi}
library(tidyverse)
library(purrr)
library(censusapi)
vars <- c(
  "B19013_001E",  # median household income estimate
  "B19013_001M"   # median household income margin of error
)

getCensus(name = "acs/acs5",
					key = Sys.getenv("CENSUS_API_KEY"),
					vars = vars, 
					region = "tract:*",
					regionin = "state:01",
					vintage = 2015) %>%
	as_tibble()
```

Smaller geographies like Census tracts can only be pulled state-by-state. This example demonstrates how to iterate across FIPS codes to pull Census tracts for multiple states. The process is as follows:

1.  Pick the variables of interest
2.  Create a vector of state FIPS codes for the states of interest
3.  Create a custom function that works on a single state FIPS code
4.  Iterate the function along the vector of state FIPS codes with `map_df()` from `library(purrr)`

Here is an example that pulls median household income at the Census tract level for multiple states:

```{r censusapi-iteration}
# variables of interest
vars <- c(
  "B19013_001E",  # median household income estimate
  "B19013_001M"   # median household income margin of error
)

# states of interest: alabama, alaska, arizona
state_fips <- c("01", "02", "04")
	
# create a custom function that works for one state
get_income <- function(state_fips) {
	
	income_data <- getCensus(name = "acs/acs5", 
													 key = Sys.getenv("CENSUS_API_KEY"),
													 vars = vars, 
													 region = "tract:*",
													 regionin = paste0("state:", state_fips),
													 vintage = 2015)
	
	return(income_data)
	
}

# iterate the function
map_df(.x = state_fips, # iterate along the vector of state fips codes
			 .f = get_income) %>% # apply get_income() to each fips_code  
	as_tibble() 
```