-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.Rmd
119 lines (86 loc) · 4.25 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
---
output: github_document
editor_options:
chunk_output_type: console
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
[](https://travis-ci.org/jjchern/saipeAPI)
[](https://ci.appveyor.com/project/jjchern/saipeAPI)
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
# About
The package `saipeAPI` provides an R client for Census Bureau's API for **S**mall **A**rea **I**ncome and **P**overty **E**stimates (SAIPE). Here is a short introduction for the SAIPE program from [Census](http://www.census.gov/data/developers/data-sets/Poverty-Statistics.html):
> The Small Area Income and Poverty Estimates (SAIPE) program produces single-year estimates of median household income and poverty for states and all counties, as well as population and poverty estimates for school districts. Since SAIPE estimates combine ACS data with administrative and other data, SAIPE estimates generally have lower variance than ACS estimates but are released later because they incorporate ACS data in the models. For counties and school districts, particularly those with populations below 65,000, the SAIPE program provides the most accurate subnational estimates of poverty. For counties, SAIPE generally provides the best single-year estimates of median household income.
# Installation
```R
# install.packages("remotes")
remotes::install_github("jjchern/[email protected]")
```
## Features
`saipeAPI` have three functions that return SAIPE data at different geographic level:
```R
saipeAPI::saipe_us()
saipeAPI::saipe_state()
saipeAPI::saipe_county()
```
## Available Geographies
Census's SAIPE has four levels of income and poverty estimates: us, state, county, and school district.
## Available Years ([Source](http://www.census.gov/data/developers/data-sets/Poverty-Statistics.html))
- State and County: 1989, 1993, 1995--2017
- School Districts: 1995, 1997, 1999--2017
## Available Variables ([Source](http://api.census.gov/data/timeseries/poverty/saipe/variables.html))
```{r, echo=FALSE}
library(dplyr, warn.conflicts = FALSE)
saipeAPI::saipe_vars %>%
select(Name, Label) %>%
knitr::kable()
```
# Usage
Obtain an API key from the U.S. Census Bureau at [http://api.census.gov/data/key_signup.html](http://api.census.gov/data/key_signup.html). After that, set your API key with the function `saipeAPI::set_api_key()`, and then start calling the data retrieval functions.
You can also save your API key in the `.Renviron` file for future usage. First, open the `.Renviron` file by
```R
# install.packages("usethis")
usethis::edit_r_environ()
```
Save your key in the file in the format of
```R
saipe_key='<Your API Key Here>'
```
Reload the `.Renviron` file and check if the key can be assessed:
```R
readRenviron("~/.Renviron")
Sys.getenv("saipe_key")
```
## National level estimates of median household income and poverty rate in 2010--2017
```{r, message=FALSE, warning=FALSE}
# saipe::set_api_key("<Your API Key Here>")
saipeAPI::saipe_us(year = 2010:2017, var = c("NAME", "SAEMHI_PT", "SAEPOVRTALL_PT"))
```
## State-level estimates of median household income and poverty rate in 2010--2017
```{r, message=FALSE, warning=FALSE}
# saipe::set_api_key("<Your API Key Here>")
saipeAPI::saipe_state(year = 2010:2017, var = c("NAME", "SAEMHI_PT", "SAEPOVRTALL_PT"))
```
## County-level data estimates of median household income and poverty rate in 2017
```{r, message=FALSE, warning=FALSE}
# saipe::set_api_key("<Your API Key Here>")
saipeAPI::saipe_county(year = 2017, var = c("NAME", "SAEMHI_PT", "SAEPOVRTALL_PT"))
```
## Possible Variables and Years
```{r, message=FALSE, warning=FALSE}
# The pacakge contains a data frame that shows possible variables and variable labels
saipeAPI::saipe_vars
# To get a vector of all possible variables
saipeAPI::saipe_vars$Name
# To get a vector of all possible years
saipeAPI::saipe_years
# Use the above two vectors to download all the US-level data
saipeAPI::saipe_us(year = saipeAPI::saipe_years, var = saipeAPI::saipe_vars$Name)
```
# Future Work
- Add school district functions