Get NHGIS time series data

Use define_nhgis_ts_extract(), ipumsr::submit_extract(), ipumsr::download_extract(), and read_nhgis_files() to define, submit, download, and read a NHGIS time series extract. This function is only recommended for interactive use and is not recommended if you are requesting a large number of tables or geographies.

Usage

get_nhgis_ts_data(
  year = NULL,
  tables = NULL,
  geography = c("county", "state"),
  extent = "us",
  output = c("tidy", "wide", "file"),
  basis = 2008,
  shape_year = NULL,
  geometry = FALSE,
  extract = NULL,
  data_file = NULL,
  shape_file = NULL,
  state = NULL,
  ...,
  time_series_tables = NULL,
  description = NULL,
  shapefiles = NULL,
  data_format = "csv_no_header",
  validate = TRUE,
  submit_extract = TRUE,
  download_extract = TRUE,
  read_files = TRUE,
  download_dir = getwd(),
  overwrite = FALSE,
  progress = TRUE,
  verbose = progress,
  api_key = Sys.getenv("IPUMS_API_KEY")
)

Arguments

output

Used to set tst_layout value. c("tidy", "wide", "file") corresponding to "time_by_row_layout", "time_by_column_layout", or "time_by_file_layout".

geometry

If TRUE, include shapefiles in the defined extract. If shapefiles is NULL, the function uses list_nhgis_shapefiles() with shape_year as the year parameter.

extract

An ipums_extract object.

data_file

Path to a .zip archive containing an NHGIS extract or a single file from an NHGIS extract.

shape_file

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

time_series_tables

List of time series table specifications for any time series tables to include in the extract request. Use tst_spec() to create a tst_spec object containing a time series table specification. See examples.

description

Description of the extract.

shapefiles

Names of any shapefiles to include in the extract request.

data_format

The desired format of the extract data file.

• "csv_no_header" (default) includes only a minimal header in the first row

• "csv_header" includes a second, more descriptive header row.

• "fixed_width" provides data in a fixed width format

Note that by default, read_nhgis() removes the additional header row in "csv_header" files.

Required when an extract definition includes any datasets or time_series_tables.

download_dir

Path to the directory where the files should be written. Defaults to current working directory.

overwrite

If TRUE, overwrite any conflicting files that already exist in download_dir. Defaults to FALSE.

progress

If TRUE, output progress bar showing the status of the download request. Defaults to TRUE.

verbose

Logical controlling whether to display output when loading data. If TRUE, displays IPUMS conditions, a progress bar, and column types. Otherwise, all are suppressed.

Will be overridden by readr.show_progress and readr.show_col_types options, if they are set.

api_key

API key associated with your user account. Defaults to the value of the IPUMS_API_KEY environment variable. See set_ipums_api_key().