Reads a area-level dataset downloaded from the IPUMS Terra extract system.

read_terra_area(data_file, data_layer = NULL, ddi_file = NULL,
  cb_file = NULL, verbose = TRUE, var_attrs = c("val_labels",
  "var_label", "var_desc"))

read_terra_area_sf(data_file, shape_file = NULL, data_layer = NULL,
  shape_layer = data_layer, shape_encoding = "UTF-8",
  ddi_file = NULL, cb_file = NULL, verbose = TRUE,
  var_attrs = c("val_labels", "var_label", "var_desc"))

read_terra_area_sp(data_file, shape_file = NULL, data_layer = NULL,
  shape_layer = data_layer, shape_encoding = "UTF-8",
  ddi_file = NULL, cb_file = NULL, verbose = TRUE,
  var_attrs = c("val_labels", "var_label", "var_desc"))

Arguments

data_file

Path to the data file, which can either be the .zip file directly downloaded from the IPUMS Terra website, path to the unzipped folder, or to the csv unzipped from the download.

data_layer

For .zip extracts with multiple datasets, the name of the data to load. Accepts a character vector specifying the file name, or dplyr_select_style conventions. Data layer must uniquely identify a dataset.

ddi_file

(Optional) If the download is unzipped, path to the .xml file which provides usage and citation information for extract.

cb_file

(Optional) If the download is unzipped, path to the .txt file which provides usage and citation information for extract.

verbose

Logical, indicating whether to print progress information to console.

var_attrs

Variable attributes to add from the DDI, defaults to adding all (val_labels, var_label and var_desc). See set_ipums_var_attributes for more details.

shape_file

(Optional) If the download is unzipped, path to the .zip, folder path or .shp file representing the the shape file. If only the data table is needed, can be set to FALSE to indicate not to load the shape file.

shape_layer

(Defaults to using the same value as data_layer) Specification of which shape files to load using the same semantics as data_layer. Can load multiple shape files, which will be combined.

shape_encoding

The text encoding to use when reading the shape file. Typically the defaults should read the data correctly, but for some extracts you may need to set them manually, but if funny characters appear in your data, you may need to. Defaults to "UTF-8" for IPUMS Terra.

Value

read_terra_area returns a tbl_df with the tabular data, read_terra_area_sf returns a sf object with tabular data and shapes, and read_terra_area_sp returns a SpatialPolygonsDataFrame with data and shapes.

See also

Examples

# NOT RUN {
data <- read_terra_area("2553_bundle.zip")
# }