/
README.Rmd
255 lines (214 loc) · 9.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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-"
)
```
# ipumsr <img src="man/figures/logo.png" align="right" height="149" width="128.5"/>
<!-- badges: start -->
[](https://www.repostatus.org/#active)
[](https://CRAN.R-project.org/package=ipumsr)
[](https://github.com/ipums/ipumsr/actions)
[](https://app.codecov.io/gh/ipums/ipumsr?branch=main)
<!-- badges: end -->
ipumsr provides an R interface for handling
[IPUMS](https://www.ipums.org) data, allowing users to:
- Easily read files downloaded from the IPUMS extract system
- Request data, download files, and get metadata from certain IPUMS
collections
- Interpret and process data using the contextual information that is
included with many IPUMS files
## Installation
To install the package from CRAN, use
```{r, eval=FALSE}
install.packages("ipumsr")
```
To install the development version of the package, use
```{r, eval=FALSE}
remotes::install_github("ipums/ipumsr")
```
## What is IPUMS?
[IPUMS](https://www.ipums.org) is the world's largest
publicly available population database, providing census and survey data
from around the world integrated across time and space. IPUMS
integration and documentation make it easy to study change, conduct
comparative research, merge information across data types, and analyze
individuals within family and community context. Data and services are
available free of charge.
IPUMS consists of multiple projects, or *collections*, that provide
different data products.
- **Microdata** projects distribute data for individual survey units,
like people or households.
- **Aggregate data** projects distribute summary tables of aggregate
statistics for particular geographic units along with corresponding
GIS mapping files.
ipumsr supports different levels of functionality for each IPUMS project, as
summarized in the table below.
```{r}
#| echo: false
checkmark <- function() {
"<img src='man/figures/check-solid.svg' class='icon-check'>"
}
# Difficult to use `proj_config()` to auto-produce this table, as we
# group projects together (e.g. Global Health projects), which is not
# reflected in `proj_config()`. Currently we will need to keep this up-to-date
# manually.
tbl_config <- list(
list(
img = "<a href='https://usa.ipums.org/usa/'><img src='man/figures/logo-square_usa_50x50.png'></a>",
proj = "<a href='https://usa.ipums.org/usa/'>IPUMS USA</a>",
type = "Microdata",
desc = "U.S. Census and American Community Survey microdata (1850-present)",
read = checkmark(),
request = checkmark(),
metadata = ""
),
list(
img = "<a href='https://cps.ipums.org/cps/'><img src='man/figures/logo-square_cps_50x50.png'></a>",
proj = "<a href='https://cps.ipums.org/cps/'>IPUMS CPS</a>",
type = "Microdata",
desc = "Current Population Survey microdata including basic monthly surveys and supplements (1962-present)",
read = checkmark(),
request = checkmark(),
metadata = ""
),
list(
img = "<a href='https://international.ipums.org/international/'><img src='man/figures/logo-square_international_50x50.png'></a>",
proj = "<a href='https://international.ipums.org/international/'>IPUMS International</a>",
type = "Microdata",
desc = "Census microdata covering over 100 countries, contemporary and historical",
read = checkmark(),
request = checkmark(),
metadata = ""
),
list(
img = "<a href='https://www.nhgis.org/'><img src='man/figures/logo-square_nhgis50x50.png'></a>",
proj = "<a href='https://www.nhgis.org/'>IPUMS NHGIS</a>",
type = "Aggregate Data",
desc = "Tabular U.S. Census data and GIS mapping files (1790-present)",
read = checkmark(),
request = checkmark(),
metadata = checkmark()
),
list(
img = "<a href='https://ihgis.ipums.org/'><img src='man/figures/logo-square_ihgis_50x50.png'></a>",
proj = "<a href='https://ihgis.ipums.org/'>IPUMS IHGIS</a>",
type = "Aggregate Data",
desc = "Tabular and GIS data from population, housing, and agricultural censuses around the world",
read = "",
request = "",
metadata = ""
),
list(
img = "<a href='https://timeuse.ipums.org/'><img src='man/figures/logo-square_time-use_50x50.png'></a>",
proj = "<a href='https://timeuse.ipums.org/'>IPUMS Time Use</a>",
type = "Microdata",
desc = "Time use microdata from the U.S. (1930-present) and thirteen other countries (1965-present)",
read = checkmark(),
request = "",
metadata = ""
),
list(
img = "<a href='https://healthsurveys.ipums.org/'><img src='man/figures/logo-square_health-surveys_50x50.png'></a>",
proj = "<a href='https://healthsurveys.ipums.org/'>IPUMS Health Surveys</a>",
type = "Microdata",
desc = paste0(
"Microdata from the U.S. ",
"<a href='https://nhis.ipums.org/nhis/'>National Health Interview Survey (NHIS)</a> (1963-present) and ",
"<a href='https://meps.ipums.org/meps/'>Medical Expenditure Panel Survey (MEPS)</a> (1996-present)"
),
read = checkmark(),
request = "",
metadata = ""
),
list(
img = "<a href='https://globalhealth.ipums.org/'><img src='man/figures/logo-square_global-health_50x50.png'></a>",
proj = "<a href='https://globalhealth.ipums.org/'>IPUMS Global Health</a>",
type = "Microdata",
desc = paste0(
"Health survey microdata for low- and middle-income countries, including ",
"harmonized data collections for <a href='https://www.idhsdata.org/'>Demographic and Health Surveys (DHS)</a> ",
"and <a href='https://pma.ipums.org/'>Performance Monitoring for Action (PMA)</a> surveys"
),
read = checkmark(),
request = "",
metadata = ""
),
list(
img = "<a href='https://highered.ipums.org/highered/'><img src='man/figures/logo-square_higher-ed_50x50.png'></a>",
proj = "<a href='https://highered.ipums.org/highered/'>IPUMS Higher Ed</a>",
type = "Microdata",
desc = "Survey microdata on the science and engineering workforce in the U.S. from 1993 to 2013",
read = checkmark(),
request = "",
metadata = ""
)
)
knitr::kable(
purrr::map_dfr(tbl_config, tibble::as_tibble),
table.attr = "class=\'table-hover table-proj-summary\'",
format = "html",
escape = FALSE,
col.names = c(
"",
"",
"Data Type",
"Description",
"Read Data Extracts",
"Request & Download Data",
"Browse Metadata"
),
align = c("clllccc")
)
```
ipumsr uses the [IPUMS API](https://developer.ipums.org/) to submit data
requests, download data extracts, and get metadata, so the scope of
functionality generally corresponds to that [available via the API](https://developer.ipums.org/docs/v2/apiprogram/apis/). As
the IPUMS team extends the API to support more functionality for more
projects, we aim to extend ipumsr capabilities accordingly.
## Getting started
If you're new to IPUMS data, learn more about what's available through
the [IPUMS Projects Overview](https://www.ipums.org/overview). Then, see
`vignette("ipums")` for an overview of how to obtain IPUMS data.
The package vignettes are the best place to explore what ipumsr has to offer:
- To read IPUMS data extracts into R, see `vignette("ipums-read")`.
- To interact with the IPUMS extract and metadata system via the IPUMS API,
see `vignette("ipums-api")`.
- For additional details about microdata and NHGIS extract requests, see
`vignette("ipums-api-micro")` and `vignette("ipums-api-nhgis")`.
- To work with labelled values in IPUMS data, see `vignette("value-labels")`.
- For techniques for working with large data extracts, see
`vignette("ipums-bigdata")`.
The [IPUMS support website](https://www.ipums.org/support) also houses
many project-specific R-based [training
exercises](https://www.ipums.org/support/exercises). However, note that some
of these exercises may not be be up to date with ipumsr's current
functionality.
## Related work
- The [survey](http://r-survey.r-forge.r-project.org/survey/) and
[srvyr](https://github.com/gergness/srvyr/) packages can help you
incorporate IPUMS survey weights into your analysis for various
survey designs.
- See [haven](https://haven.tidyverse.org/index.html) for more
information about value labels and labelled vectors
- [hipread](https://github.com/ipums/hipread) underlies the
hierarchical file reading functions in ipumsr
## Getting help + contributing
We greatly appreciate feedback and development contributions. Please
submit any bug reports, pull requests, or other suggestions on
[GitHub](https://github.com/ipums/ipumsr/issues). Before contributing,
please be sure to read the [Contributing
Guidelines](https://tech.popdata.org/ipumsr/CONTRIBUTING.html)
and the
[Code of Conduct](https://tech.popdata.org/ipumsr/CODE_OF_CONDUCT.html).
If you have general questions or concerns about IPUMS data, check out
our [user forum](https://forum.ipums.org) or send an email to
[ipums\@umn.edu](mailto:ipums@umn.edu){.email}.