Create dataset and time series table specifications for IPUMS NHGIS extract requests

Provide specifications for individual datasets and time series tables when defining an IPUMS NHGIS extract request.

Use get_metadata_nhgis() to identify available values for dataset and time series table specification parameters.

Learn more about NHGIS extract definitions in vignette("ipums-api-nhgis").

Usage

ds_spec(
  name,
  data_tables = NULL,
  geog_levels = NULL,
  years = NULL,
  breakdown_values = NULL
)

tst_spec(name, geog_levels = NULL, years = NULL)

Arguments

name

Name of the dataset or time series table.

data_tables

Vector of summary tables to retrieve for the given dataset.

geog_levels

Geographic levels (e.g. "county" or "state") at which to obtain data for the given dataset or time series table.

years

Years for which to obtain the data for the given dataset or time series table.

For time series tables, all years are selected by default. For datasets, use "*" to select all available years. Use get_metadata_nhgis() to determine if a dataset allows year selection.

breakdown_values

Breakdown values to apply to the given dataset.

Value

A ds_spec or tst_spec object.

Details

In general, data_tables and geog_levels are required for all dataset specifications, and geog_levels are required for all time series table specifications.

However, it is possible to make a temporary specification for an incomplete dataset or time series table by omitting these values. This supports the syntax used when modifying an existing extract (see add_to_extract() or remove_from_extract()).

Examples

dataset <- ds_spec(
  "2013_2017_ACS5a",
  data_tables = c("B00001", "B01002"),
  geog_levels = "state"
)

tst <- tst_spec(
  "CW5",
  geog_levels = c("county", "tract"),
  years = "1990"
)

# Use variable specifications in an extract definition:
define_extract_nhgis(
  description = "Example extract",
  datasets = dataset,
  time_series_tables = tst
)
#> Unsubmitted IPUMS NHGIS extract 
#> Description: Example extract
#> 
#> Dataset: 2013_2017_ACS5a
#>   Tables: B00001, B01002
#>   Geog Levels: state
#> 
#> Time Series Table: CW5
#>   Geog Levels: county, tract
#>   Years: 1990