Skip to content

ipums/ipumsr

Repository files navigation

ipumsr

Project Status:Active CRAN_Status_Badge R build status Codecov test coverage

ipumsr provides an R interface for handling IPUMS 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

install.packages("ipumsr")

To install the development version of the package, use

remotes::install_github("ipums/ipumsr")

What is IPUMS?

IPUMS 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.

Data Type Description Read Data Extracts Request & Download Data Browse Metadata
IPUMS USA logo IPUMS USA Microdata U.S. Census and American Community Survey microdata (1850-present) Check mark Check mark
IPUMS CPS logo IPUMS CPS Microdata Current Population Survey microdata including basic monthly surveys and supplements (1962-present) Check mark Check mark
IPUMS International logo IPUMS International Microdata Census microdata covering over 100 countries, contemporary and historical Check mark Check mark
IPUMS NHGIS logo IPUMS NHGIS Aggregate Data Tabular U.S. Census data and GIS mapping files (1790-present) Check mark Check mark Check mark
IPUMS IHGIS logo IPUMS IHGIS Aggregate Data Tabular and GIS data from population, housing, and agricultural censuses around the world
IPUMS Time Use logo IPUMS Time Use Microdata Time use microdata from the U.S. (1930-present) and thirteen other countries (1965-present) Check mark Check mark
IPUMS Health Surveys logo IPUMS Health Surveys Microdata Microdata from the U.S. National Health Interview Survey (NHIS) (1963-present) and Medical Expenditure Panel Survey (MEPS) (1996-present) Check mark Check mark
IPUMS Global Health logo IPUMS Global Health Microdata Health survey microdata for low- and middle-income countries, including harmonized data collections for Demographic and Health Surveys (DHS) and Performance Monitoring for Action (PMA) surveys Check mark
IPUMS Higher Ed logo IPUMS Higher Ed Microdata Survey microdata on the science and engineering workforce in the U.S. from 1993 to 2013 Check mark

ipumsr uses the IPUMS API to submit data requests, download data extracts, and get metadata, so the scope of functionality generally corresponds to that available via the API. 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. 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 also houses many project-specific R-based training exercises. However, note that some of these exercises may not be be up to date with ipumsr’s current functionality.

Related work

  • The survey and srvyr packages can help you incorporate IPUMS survey weights into your analysis for various survey designs.

  • See haven for more information about value labels and labelled vectors

  • 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. Before contributing, please be sure to read the Contributing Guidelines and the Code of Conduct.

If you have general questions or concerns about IPUMS data, check out our user forum or send an email to ipums@umn.edu.