ipumsr (version 0.5.2)

is_extract_ready: Is the extract ready to download?

Description

This function uses the IPUMS API to check whether the given extract is ready to download, returning TRUE for extracts that are ready and FALSE for those that are not. For an overview of ipumsr microdata API functionality, see vignette("ipums-api", package = "ipumsr").

Usage

is_extract_ready(extract, api_key = Sys.getenv("IPUMS_API_KEY"))

Value

A logical vector of length one.

Arguments

extract

One of:

• An ipums_extract object

• The data collection and extract number formatted as a single string of the form "collection:number"

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

The extract number does not need to be zero-padded (e.g., use "usa:1" or c("usa", "1"), not "usa:00001" or c("usa", "00001")). See Examples section below for examples of each form.

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

api_key

API key associated with your user account. Defaults to the value of environment variable "IPUMS_API_KEY".

Details

This function checks the "download_links" element of the supplied extract to determine whether the extract files are available to download. The "status" of a submitted extract is one of "queued", "started", "produced", "canceled", "failed", or "completed". Only "completed" extracts can be ready to download, but not all "completed" extracts are ready to download, because extract files are subject to removal from the IPUMS servers 72 hours after they first become available. Completed extracts older than 72 hours will still have a "completed" status, but will return FALSE from is_extract_ready(), because the extract files are no longer available.

See Also

Other ipums_api: add_to_extract(), define_extract_cps(), define_extract_from_json(), define_extract_usa(), download_extract(), extract_list_to_tbl(), extract_tbl_to_list(), get_extract_info(), get_last_extract_info(), get_recent_extracts_info, ipums_data_collections(), remove_from_extract(), save_extract_as_json(), set_ipums_api_key(), submit_extract(), wait_for_extract()

Examples

my_extract <- define_extract_usa("Example", "us2013a", "YEAR")

if (FALSE) {
submitted_extract <- submit_extract(my_extract)

# Check if extract is ready by supplying an ipums_extract object:
is_extract_ready(submitted_extract)

# By supplying the data collection and extract number, as a string:
is_extract_ready("usa:1")
# Note that there is no space before or after the colon, and no zero-padding
# of the extract number.

# By supplying the data collection and extract number, as a vector:
is_extract_ready(c("usa", "1"))
}