ipumsr (version 0.6.3)

read_ipums_sp: Read boundary (GIS) files from an IPUMS extract

Description

Read spatial data from an IPUMS extract into R using the sp package.

This function has been deprecated because of the upcoming retirement of the rgdal package. For more information, click here.

Please use read_ipums_sf() to load spatial data from IPUMS. To convert to a SpatialPolygonsDataFrame, use sf::as_Spatial().

Usage

read_ipums_sp(
  shape_file,
  shape_layer = NULL,
  vars = NULL,
  encoding = NULL,
  bind_multiple = TRUE,
  add_layer_var = NULL,
  verbose = TRUE
)

Value

A SpatialPolygonsDataFrame or SpatialPointsDataFrame object.

Arguments

shape_file

Path to a single .shp file or a .zip archive containing at least one .shp file. See Details section.

shape_layer

If shape_file contains multiple files, an expression identifying the files to load. Accepts a character string specifying the file name, a tidyselect selection, or index position. If multiple files are selected, bind_multiple must be equal to TRUE.

vars

Names of variables to include in the output. Accepts a character vector of names or a tidyselect selection. If NULL, includes all variables in the file.

encoding

Encoding to use when reading the shape file. If NULL, defaults to "latin1" unless the file includes a .cpg metadata file with encoding information. The default value should generally be appropriate.

bind_multiple

If TRUE and shape_file contains multiple .shp files, row-bind the files into a single output. Note that some data sources may not be able to be combined (e.g. SpatialPolygonsDataFrame and SpatialPointsDataFrame).

add_layer_var

If TRUE, add a variable to the output data indicating the file that each row originates from. Defaults to FALSE unless bind_multiple = TRUE and multiple files exist in shape_file.

The column name will always be prefixed with "layer", but will be adjusted to avoid name conflicts if another column named "layer" already exists in the data.

verbose

If TRUE, report progress information.

Details

Some IPUMS products provide shapefiles in a "nested" .zip archive. That is, each shapefile (including a .shp as well as accompanying files) is compressed in its own archive, and the collection of all shapefiles provided in an extract are also compressed into a single .zip archive.

read_ipums_sp() is designed to handle this structure. However, if an internal .zip archive happens to contain multiple shapefiles, this function will throw an error. If this is the case, you may need to manually unzip the downloaded file before loading it into R.

Examples

shape_file <- ipums_example("nhgis0972_shape_small.zip")

# If sp package is available, can load as SpatialPolygonsDataFrame
if (require(sp) && require(rgdal)) {
  sp_data <- read_ipums_sp(shape_file, verbose = FALSE)
}