is_extract_ready: Is the extract ready to download?

In mnpopcenter/ipumsr: Read 'IPUMS' Extract Files

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 API functionality, see vignette("ipums-api", package = "ipumsr").

Usage

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

Arguments

extract

One of: An object of class ipums_extract 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.

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.

Value

A logical vector of length one.

See Also

Other ipums_api: define_extract_from_json(), define_extract_micro(), download_extract(), extract_list_to_tbl(), extract_tbl_to_list(), get_extract_info(), get_last_extract_info(), get_recent_extracts_info, ipums_data_collections(), revise_extract_micro(), save_extract_as_json(), submit_extract(), wait_for_extract()

Examples

my_extract <- define_extract_micro("usa", "Example", "us2013a", "YEAR")

## Not run: 
submitted_extract <- submit_extract(my_extract)

# Check if extract is ready by supplying 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"))

## End(Not run)

mnpopcenter/ipumsr documentation built on Sept. 30, 2022, 6:56 a.m.