Package 'ipumseasyr'

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".

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.

Arguments passed on to ipumsr::define_extract_nhgis

datasets

List of dataset specifications for any datasets to include in the extract request. Use ds_spec() to create a ds_spec object containing a dataset specification. See examples.

geographic_extents

Vector of geographic extents to use for all of the datasets in the extract definition (for instance, to obtain data within a particular state). Use "*" to select all available extents.

Required when any of the datasets included in the extract definition include geog_levels that require extent selection. See get_metadata_nhgis() to determine if a geographic level requires extent selection. At the time of writing, NHGIS supports extent selection only for blocks and block groups.

breakdown_and_data_type_layout

The desired layout of any datasets that have multiple data types or breakdown values.

• "single_file" (default) keeps all data types and breakdown values in one file

• "separate_files" splits each data type or breakdown value into its own file

Required if any datasets included in the extract definition consist of multiple data types (for instance, estimates and margins of error) or have multiple breakdown values specified. See get_metadata_nhgis() to determine whether a requested dataset has multiple data types.

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 of the extract.

Names of any shapefiles to include in the extract request.

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.

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

One of:

• An ipums_extract object

• The data collection and extract number formatted as a string of the form "collection:number" or as a vector of the form c("collection", number)

• An extract number to be associated with your default IPUMS collection. See set_ipums_default_collection()

For a list of codes used to refer to each collection, see ipums_data_collections().

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

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

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

Arguments passed on to ipumsr::wait_for_extract

initial_delay_seconds

Seconds to wait before first status check. The wait time will automatically increase by 10 seconds between each successive check.

max_delay_seconds

Maximum interval to wait between status checks. When the wait interval reaches this value, checks will continue to occur at max_delay_seconds intervals until the extract is complete or timeout_seconds is reached. Defaults to 300 seconds (5 minutes).

timeout_seconds

Maximum total number of seconds to continue waiting for the extract before throwing an error. Defaults to 10,800 seconds (3 hours).

verbose

If TRUE, print status updates to the R console at the beginning of each wait interval and upon extract completion. Defaults to TRUE.

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

An ipums_extract object.

If extract is not NULL and submit_extract = TRUE, use ipumsr::submit_extract to submit the extract.

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

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

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

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

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".

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.

An ipums_extract object.

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

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

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 of the extract.

Names of any shapefiles to include in the extract request.

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.

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

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

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

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 associated with your user account. Defaults to the value of the IPUMS_API_KEY environment variable. See set_ipums_api_key().

Reference year to use when calculating a percent change column.

Passed to x and n arguments of dplyr::ntile() to join a reference rank value.

Used as .by argument of dplyr::mutate() if rank_n is not NULL.

Arguments passed on to ggplot2::labs

title

The text for the title.

subtitle

The text for the subtitle for the plot which will be displayed below the title.

caption

The text for the caption which will be displayed in the bottom-right of the plot by default.

tag

The text for the tag label which will be displayed at the top-left of the plot by default.

alt,alt_insight

Text used for the generation of alt-text for the plot. See get_alt_text for examples.

Credit line for IPUMS.

String to collapse caption and credit. Defaults to " ". Set to "\n" to place the credit line on a separate line following the caption. Ignored if caption is NULL.

Maximum width of caption line passed to stringr::str_wrap().

Additional parameters passed to ipumsr::get_metadata_nhgis()

If FALSE, do not read a file from cache. If TRUE, read a file from cache if it exists at the supplied path.

Optional filter for geographical integration.

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

If shape_file is a .zip archive that 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.

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 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.

If TRUE and shape_file contains multiple .shp files, row-bind the files into a single sf object. Useful when shape_file contains multiple files that represent the same geographic units for different extents (e.g. block-level data for multiple states).

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.

If TRUE report additional progress information on load.

Optional if data_file is supplied. A named list with a "data" and "shape" element containing the paths to the data_file and shape_file arguments of used by ipumsr::read_nhgis() and ipumsr::read_ipums_sf().

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

Passed to file_select parameter of read_nhgis_data() or read_ipums_geometry().

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

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.