ipumsr (version 0.4.5)

read_nhgis: Read data from an NHGIS extract

Description

Reads a dataset downloaded from the NHGIS extract system. Relies on csv files (with or without the extra header row).

Usage

read_nhgis(
  data_file,
  data_layer = NULL,
  verbose = TRUE,
  var_attrs = c("val_labels", "var_label", "var_desc")
)
read_nhgis_sf(
  data_file,
  shape_file,
  data_layer = NULL,
  shape_layer = data_layer,
  shape_encoding = "latin1",
  verbose = TRUE,
  var_attrs = c("val_labels", "var_label", "var_desc")
)
read_nhgis_sp(
  data_file,
  shape_file,
  data_layer = NULL,
  shape_layer = data_layer,
  shape_encoding = "latin1",
  verbose = TRUE,
  var_attrs = c("val_labels", "var_label", "var_desc")
)

Arguments

data_file

Filepath to the data (either the .zip file directly downloaded from the website, the path to the unzipped folder, or the path to the unzipped .csv file directly).

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.

verbose

Logical, indicating whether to print progress information to console.

var_attrs

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

shape_file

Filepath to the shape files (either the .zip file directly downloaded from the website, or the path to the unzipped folder, or the unzipped .shp file directly).

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 "latin1" for NHGIS.

Value

read_nhgis returns a tbl_df with only the tabular data, read_nhgis_sf returns a sf object with data and the shapes, and read_nhgis_sp returns a SpatialPolygonsDataFrame with data and shapes.

See Also

Other ipums_read: read_ipums_micro_chunked(), read_ipums_micro_yield(), read_ipums_micro(), read_ipums_sf(), read_terra_area(), read_terra_micro(), read_terra_raster()

Examples

# NOT RUN {
csv_file <- ipums_example("nhgis0008_csv.zip")
shape_file <- ipums_example("nhgis0008_shape_small.zip")

data_only <- read_nhgis(csv_file)

# If sf package is availble, can load as sf object
if (require(sf)) {
  sf_data <- read_nhgis_sf(csv_file, shape_file)
}

# If sp package is available, can load as SpatialPolygonsDataFrame
if (require(rgdal) && require(sp)) {
  sp_data <- read_nhgis_sp(csv_file, shape_file)
}

# }